Eu tenho uma imagem do docker que recebe um conjunto de variáveis ​​de ambiente para personalizar sua execução.

Um exemplo simples seria um servidor Web, que possui coisas como o segredo do cliente para o OAuth2, um segredo para assinar cookies etc.

Todo o aplicativo é contêiner em uma imagem do docker, que recebe variáveis ​​de ambiente (tempo de execução).

Eu distribuo essa imagem de janela de encaixe em um registro privado e gostaria de documentá-la, para que os usuários possam entender como podem personalizar a imagem.

É possível enviar, como parte da imagem do Docker, anotações que, por exemplo, usando docker describe my_imagea marcação de saída para o stdout?

É claro que eu poderia usar uma página estática na Web para documentação, mas o usuário ainda precisaria saber onde essa documentação poderia ser encontrada, e toda a distribuição seria mais complementada dessa maneira (por exemplo, a documentação muda com a tag da imagem).

Alguma ideia?

Até onde eu sei, não há nenhuma bala de prata. Todas as soluções abaixo funcionam, mas exigem que o usuário seja informado sobre como recuperar a documentação. Não existe uma maneira padrão de fazê-lo .

A iniciativa de contêiner aberto criou uma anotação de especificação de imagem sugerindo que

• Um link para mais informações sobre a imagem deve ser fornecido em um selo chamado org.opencontainers.image.documentation.
• Uma descrição do software empacotado dentro do contêiner deve ser fornecida em um rótulo chamado org.opencontainers.image.description

De acordo com a OCI, uma das variações da opção 1 abaixo está correta.

Opção 1: Fornecer um link em um rótulo (preferido pela OCI )

Supondo que o Dockerfile e os ativos relacionados sejam controlados por versão em um repositório git acessível ao público (por exemplo, no github), esse repositório git também pode conter um arquivo README.md. Se você tiver um pipeline conectado ao repositório que cria e publica a imagem do Docker em um registro automaticamente, poderá configurar o comando docker build para adicionar um rótulo com um link para a documentação da seguinte maneira

# 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 solução vincula a documentação de confirmação específica para essa confirmação específica com versão juntamente com o Dockerfile. No entanto, exige que o usuário tenha acesso à Internet para poder ler a documentação

Opção 1b: Fornecendo documentação completa em um rótulo (Preferido pela OCI )

Uma variação da opção 1, onde a documentação completa é serializada e colocada na etiqueta (não há restrições de comprimento nas etiquetas). Dessa forma, a documentação é empacotada com a própria imagem

Como Jorge Leitao apontou nos comentários, a especificação de anotação de imagem da OCI especifica o nome de um rótulo comoorg.opencontainers.image.description

Opção 2: Agrupando documentação dentro da imagem

Se você preferir realmente agrupar o arquivo Leiame.md dentro da imagem para torná-lo independente em qualquer página da web externa, considere o seguinte

Na criação, certifique-se de copiar o arquivo Leiame.md para a imagem do docker Crie também um script de shell simples describeque inclua o Leiame.md

descrever

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

Adições ao Dockerfile

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

Um usuário que possui sua imagem do Docker e agora executa o comando a seguir para enviar a remarcação para stdout

docker run myimage:version describe

Esta solução agrupa a documentação para esta versão específica da imagem dentro da imagem e pode ser recuperada sem nenhuma dependência externa