Tengo una imagen acoplable que recibe un conjunto de variables de entorno para personalizar su ejecución.

Un ejemplo simple sería un servidor web, que tiene cosas como el secreto del cliente para OAuth2, un secreto para firmar cookies, etc.

Toda la aplicación está en contenedores en una imagen acoplable, que recibe variables de entorno (tiempo de ejecución).

Distribuyo esa imagen de la ventana acoplable en un registro privado, y me gustaría documentar esa imagen, para que los usuarios puedan entender cómo pueden personalizar la imagen.

¿Es posible enviar, como parte de la imagen de la ventana acoplable, anotaciones que, por ejemplo, utilizan docker describe my_imagela reducción de salida a la salida estándar?

Por supuesto, podría usar una página estática en la web para la documentación, pero el usuario aún necesitaría saber dónde se puede encontrar esa documentación, y toda la distribución sería más completa de esta manera (por ejemplo, la documentación cambia con la etiqueta de imagen).

¿Algunas ideas?

No hay una bala de plata aquí hasta donde yo sé. Todas las soluciones a continuación funcionan, pero requieren que se informe al usuario sobre cómo recuperar la documentación. No hay una forma estándar de hacerlo .

La iniciativa de contenedor abierto ha creado una anotación de especificaciones de imagen que sugiere que

• Se debe proporcionar un enlace a más información sobre la imagen en una etiqueta llamada org.opencontainers.image.documentation.
• Se debe proporcionar una descripción del software empaquetado dentro del contenedor en una etiqueta llamada org.opencontainers.image.description

Según OCI, una de las variaciones de la opción 1 a continuación es correcta.

Opción 1: Proporcionar un enlace en una etiqueta (Preferido por OCI )

Suponiendo que el Dockerfile y los activos relacionados están controlados por la versión en un repositorio git que es de acceso público (por ejemplo, en github), ese repositorio git también podría contener un archivo README.md. Si tiene una tubería conectada al repositorio que construye y publica la imagen de Docker en un registro automáticamente, puede configurar el comando de compilación de Docker para agregar una etiqueta con un enlace a la documentación de la siguiente manera

# Get the current commit id
commit=$(git rev-parse HEAD)

# Build docker image and attach a link to the Readme as a label
docker build -t myimagename:myversion \
--label "org.opencontainers.image.documentation=https://github.com/<user>/<repo>/blob/$commit/README.md"

Esta solución se vincula a documentación de confirmación específica para esa confirmación particular versionada junto con su Dockerfile. Sin embargo, requiere que el usuario tenga acceso a Internet para poder leer la documentación

Opción 1b: Proporcionar documentación completa en una etiqueta (Preferido por OCI )

Una variación de la opción 1 donde la documentación completa se serializa y se coloca en la etiqueta (no hay restricciones de longitud en las etiquetas). De esta forma, la documentación se incluye con la imagen misma.

Como señaló Jorge Leitao en los comentarios, la especificación de anotación de imagen de OCI especifica el nombre de una etiqueta comoorg.opencontainers.image.description

Opción 2: agrupación de documentación dentro de la imagen

Si prefiere agrupar el archivo Readme.md dentro de la imagen para que sea independiente de cualquier página web externa, tenga en cuenta lo siguiente

Al compilar, asegúrese de copiar el archivo Readme.md a la imagen del acoplador. También cree un script de shell simple describeque genere el archivo Readme.md

describir

#!/usr/bin/env sh
cat /docs/Readme.md

Adiciones de archivos Docker

...
COPY Readme.md /docs/Readme.md
COPY describe /opt/bin/describe
RUN chmod +x /opt/bin/describe
ENV PATH="/opt/bin:${PATH}"
...

Un usuario que tenga su imagen de Docker ahora puede ejecutar el siguiente comando para que se envíe la rebaja a stdout

docker run myimage:version describe

Esta solución incluye la documentación de esta versión particular de la imagen dentro de la imagen y se puede recuperar sin ninguna dependencia externa.