如何记录 docker 镜像

Question

我有一个 docker 镜像，它接收一组环境变量来自定义其执行。

一个简单的例子是一个网络服务器，它有像 OAuth2 的客户端秘密，签署 cookie 的秘密等等。

整个应用程序被容器化在一个 docker 镜像上，它接收（运行时）环境变量。

我将那个 docker 镜像分发到一个私有注册中心，我想记录这个镜像，以便用户可以了解他们如何自定义镜像。

是否可以将注释作为 docker 映像的一部分docker describe my_image发送到标准输出，例如使用 输出降价？

我当然可以使用 Web 上的静态页面作为文档，但用户仍然需要知道在哪里可以找到该文档，并且整个分发会以这种方式更加复杂（例如，文档更改为图像标签）。

有任何想法吗？

Answer 1

据我所知，这里没有灵丹妙药，下面的所有解决方案都有效，但需要告知用户如何检索文档。 没有标准的方法来做到这一点。

开放容器倡议创建了一个图像规范注释，表明

• 应在名为 的标签中提供指向有关图像的更多信息的链接org.opencontainers.image.documentation。
• 容器内打包的软件的描述应在名为的标签中提供org.opencontainers.image.description

根据 OCI，以下选项 1 的变体之一是正确的。

选项 1：在标签中提供链接（OCI首选）

假设 Dockerfile 和相关资产在可公开访问的 git 存储库中进行版本控制（例如在 github 上），则该 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 的变体，其中完整文档被序列化并放入标签中（标签没有长度限制）。这样，文档就与图像本身捆绑在一起了

正如Jorge Leitao在评论中指出的那样，OCI 的图像注释规范将此类标签的名称指定为org.opencontainers.image.description

选项 2：将文档捆绑在图像内

如果您希望将 Readme.md 文件实际捆绑在图像中以使其独立于任何外部网页，请考虑以下内容

构建后，请确保将 Readme.md 文件复制到 docker 镜像。同时创建一个简单的 shell 脚本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 镜像的用户现在运行以下命令将 markdown 发送到 stdout

docker run myimage:version describe

该解决方案将特定版本图像的文档捆绑在图像内，无需任何外部依赖即可检索它