如何使用 docker manifest annotate 命令添加平台信息

简介

在本次实验中，你将学习如何使用 docker manifest annotate 命令向 Docker 清单列表（manifest list）添加平台信息。我们将从创建一个包含 alpine 镜像不同架构版本的清单列表开始。

创建完清单列表后，你将练习为列表中的各个清单添加注释，以指定架构、操作系统、操作系统特性、版本和架构变体。最后，你将检查添加了注释的清单列表，以验证所添加的平台信息。这个过程对于有效构建和分发多架构 Docker 镜像至关重要。

Skills Graph

创建清单列表

在这一步中，你将学习如何创建一个清单列表（manifest list）。清单列表是镜像清单（image manifest）的索引，它允许你使用一个名称引用适用于不同架构和操作系统的多个镜像。这对于分发多架构镜像特别有用。

在创建清单列表之前，你需要准备一些可用的镜像。在本次实验中，你将使用不同架构的 alpine 镜像。你将拉取 alpine 镜像的 amd64 和 arm64 版本。

首先，拉取 alpine 镜像的 amd64 版本：

docker pull alpine:latest

你应该会看到显示正在拉取和提取镜像的输出信息。

接下来，拉取 alpine 镜像的 arm64 版本。注意，这次拉取时你需要指定平台。

docker pull --platform arm64 alpine:latest

同样，你会看到显示正在拉取镜像的输出信息。

现在你已经有了这些镜像，就可以创建清单列表了。你将使用 docker manifest create 命令。该命令需要你指定要创建的清单列表的名称，后面跟着要包含在列表中的镜像名称。

让我们创建一个名为 my-alpine-list 的清单列表，其中包含 alpine:latest（amd64）和 alpine:latest（arm64）镜像。

docker manifest create my-alpine-list alpine:latest alpine:latest --amend --amend

--amend 标志用于在清单列表中添加或更新条目。这里使用了两次该标志，因为你要添加两个镜像。

运行此命令后，你就创建了一个清单列表。不过，目前这个列表仅存储在本地。在后续步骤中，你将把它推送到镜像仓库（registry）。

为清单添加架构和操作系统注释

在这一步中，你将为上一步创建的清单列表添加注释。为清单添加注释可以让你向其中添加元数据，例如镜像所适用的架构和操作系统。这些信息对于 Docker 根据容器运行的环境从清单列表中选择正确的镜像至关重要。

你将使用 docker manifest annotate 命令为 my-alpine-list 清单列表中的条目添加架构和操作系统信息。该命令需要指定清单列表名称、列表中的镜像名称以及注释标志。

首先，为对应 amd64 架构和 linux 操作系统的 alpine:latest 镜像添加注释。

docker manifest annotate my-alpine-list alpine:latest --arch amd64 --os linux

此命令告知 Docker，my-alpine-list 清单中的 alpine:latest 镜像适用于 amd64 架构和 linux 操作系统。

接下来，为对应 arm64 架构和 linux 操作系统的 alpine:latest 镜像添加注释。

docker manifest annotate my-alpine-list alpine:latest --arch arm64 --os linux

此命令为列表中的另一个 alpine:latest 镜像添加注释，指定它适用于 arm64 架构和 linux 操作系统。

通过为清单列表添加架构和操作系统信息注释，当用户在具有特定架构的系统上拉取 my-alpine-list 时，Docker 就能够自动选择正确的镜像。

为清单添加操作系统特性和版本注释

在这一步中，你将继续为清单列表添加注释，补充有关操作系统特性和版本的信息。虽然对于像 Alpine 这样的基础镜像来说，这些注释不太常见，但对于那些需要特定操作系统功能或版本的镜像而言，这些注释会很有用。

docker manifest annotate 命令允许你使用 --os-features 标志指定操作系统特性，使用 --os-version 标志指定操作系统版本。

为了便于演示，假设你的 amd64 Alpine 镜像需要特定的操作系统特性（例如 fips），并且是为特定的操作系统版本（例如 1.0）构建的。你将使用这些信息为 my-alpine-list 中的 amd64 条目添加注释。

docker manifest annotate my-alpine-list alpine:latest --arch amd64 --os linux --os-features fips --os-version 1.0

此命令更新了 my-alpine-list 中 amd64 条目的注释，添加了指定的操作系统特性和版本。

同样，假设你的 arm64 Alpine 镜像需要不同的操作系统特性（例如 selinux），并且是为不同的操作系统版本（例如 2.0）构建的。你将为 arm64 条目添加注释。

docker manifest annotate my-alpine-list alpine:latest --arch arm64 --os linux --os-features selinux --os-version 2.0

此命令更新了 arm64 条目的注释，添加了其特定的操作系统特性和版本。

通过添加这些注释，你可以提供有关镜像要求和兼容性的更详细信息，Docker 或其他工具在从清单列表中选择镜像时可以利用这些信息。

为清单添加架构变体注释

在这一步中，你将为清单列表添加架构变体信息。架构变体用于区分同一架构的不同版本或实现。例如，arm 架构有 v6、v7 和 v8 等变体。

你可以使用 docker manifest annotate 命令搭配 --variant 标志来指定架构变体。

假设你的 arm64 Alpine 镜像专门为 arm64 架构的 v8 变体构建。你将使用此信息为 my-alpine-list 中的 arm64 条目添加注释。

docker manifest annotate my-alpine-list alpine:latest --arch arm64 --os linux --variant v8

此命令更新了 my-alpine-list 中 arm64 条目的注释，添加了 v8 变体信息。

对于 amd64 架构，变体不太常见，但如果需要，你也可以指定一个。在本实验中，你不会为 amd64 条目添加变体信息。

通过添加架构变体信息，你可以提供关于镜像兼容性的更具体细节，使 Docker 能够为给定系统选择最合适的镜像。

检查添加了注释的清单列表

在最后这一步，你将检查已创建并添加了注释的清单列表，查看你所添加的信息。docker manifest inspect 命令可让你查看清单列表的详细信息，包括其中包含的清单及其注释。

要检查你的 my-alpine-list 清单列表，请运行以下命令：

docker manifest inspect my-alpine-list

此命令将输出一个表示清单列表的 JSON 文档。你应该会看到 amd64 和 arm64 镜像的条目，以及你在前面步骤中添加的注释，例如 architecture、os、os.features、os.version 和 variant。

在输出中查找 manifests 数组。该数组中的每个对象都代表清单列表中包含的一个镜像。你应该能够在每个清单对象中找到 platform 字段，其中包含 architecture、os、os.features 和 os.version 信息。对于 arm64 条目，你还应该能看到 variant 字段。

检查清单列表是验证注释是否已正确应用以及清单列表是否按你预期配置的好方法。

总结

在本实验中，你学习了如何创建 Docker 清单列表。清单列表可作为多个镜像清单的索引，能让你以单一名称分发多架构镜像。首先，你拉取了适用于 amd64 和 arm64 架构的 alpine 镜像。接着，你使用 docker manifest create 命令搭配 --amend 标志，构建了一个名为 my-alpine-list 的本地清单列表，并将拉取的镜像包含其中。

创建清单列表后，你了解了如何使用 docker manifest annotate 命令为列表中的各个清单添加注释。此过程包括添加关键元数据，如架构和操作系统信息。你特别学习了如何为清单添加架构和操作系统详细信息，还进一步了解了如何添加操作系统特性、版本和架构变体信息。最后，你学习了如何检查添加了注释的清单列表，以验证所添加的元数据，确保列表准确反映所包含镜像的特性。