実行をカスタマイズするための環境変数のセットを受け取るDockerイメージがあります。

簡単な例は、OAuth2のクライアントシークレット、Cookieに署名するためのシークレットなどのWebサーバーです。

アプリ全体が、（ランタイム）環境変数を受け取るDockerイメージにコンテナ化されます。

私はそのdockerイメージをプライベートレジストリで配布しています。ユーザーがイメージをカスタマイズする方法を理解できるように、そのイメージを文書化したいと思います。

たとえば、docker describe my_image出力マークダウンを使用してstdoutに出力するアノテーションを、Dockerイメージの一部として出荷することはでき ますか？

もちろん、ドキュメントのWeb上の静的ページを使用することもできますが、ユーザーはそのドキュメントがどこにあるかを知る必要があり、配布全体がこのように複雑になります（たとえば、イメージタグによるドキュメントの変更）。

何か案は？

私が知る限り、ここに特効薬はありません。以下のすべてのソリューションは機能しますが、ドキュメントを取得する方法をユーザーに通知する必要があります。 それを行うための標準的な方法はありません。

開放容器のイニシアチブは、作成した画像スペック注釈ことを示唆しているが

• 画像に関する詳細情報へのリンクは、というラベルで提供する必要がありますorg.opencontainers.image.documentation。
• コンテナ内にパッケージされているソフトウェアの説明は、 org.opencontainers.image.description

OCIによると、以下のオプション1のバリエーションの1つが正しいです。

オプション1：ラベルにリンクを提供する（OCIが推奨）

Dockerfileと関連アセットが、（githubなどで）公にアクセス可能なgitリポジトリでバージョン管理されていると仮定すると、そのgitリポジトリにはREADME.mdファイルも含めることができます。Dockerイメージをビルドしてレジストリに自動的に公開するリポジトリにパイプラインを接続している場合、次のように、docker buildコマンドを設定して、ドキュメントへのリンクを含むラベルを追加できます。

# 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"

このソリューションは、Dockerfileと一緒にバージョン管理された特定のコミットの特定のコミットドキュメントにリンクしています。ただし、ドキュメントを読むには、ユーザーがインターネットにアクセスできる必要があります。

オプション1b：ラベルで完全なドキュメントを提供する（OCIが推奨）

完全なドキュメントがシリアル化されてラベルに入れられるオプション1のバリエーション（ラベルの長さ制限はありません）。このように、ドキュメントは画像自体にバンドルされています

ジョージ・ライタオはコメントで指摘し、OCIから画像annotaionの仕様では、このようなAのラベルの名前を指定しますorg.opencontainers.image.description

オプション2：画像内にドキュメントをバンドルする

Readme.mdファイルを画像内に実際にバンドルして、外部Webページから独立させる場合は、以下を検討してください。

ビルド時に、必ずReadme.mdファイルをDockerイメージにコピーしてくださいまたdescribe、Readme.mdをキャットする簡単なシェルスクリプトを作成してください

説明する

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

Dockerfileの追加

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

Dockerイメージを持っているユーザーは、次のコマンドを実行して、マークダウンをstdoutに送信します

docker run myimage:version describe

このソリューションは、イメージ内のこの特定のバージョンのイメージのドキュメントをバンドルしており、外部の依存関係なしで取得できます。