附注

注释为镜像提供描述性元数据。使用注释进行记录任意信息并将其附加到您的镜像上，这有助于消费者和工具了解镜像的来源、内容以及如何使用镜像。

注释类似于标签，在某种意义上与标签重叠。双具有相同的目的：将元数据附加到资源。作为一般原则，您可以将注释和标签之间的区别视为：

注释描述 OCI 镜像组件，例如清单、索引、和描述符。
标签描述 Docker 资源，例如镜像、容器、网络和卷。

OCI 镜像规范定义了注释的格式以及一组预定义的注释键。遵守规定的标准可确保有关镜像的元数据可以通过以下方式自动且一致地显示 Docker Scout 等工具。

注释不要与证明混淆：

证明包含有关镜像的构建方式及其包含的内容的信息。证明作为单独的清单附加到 image 索引上。 Open Container Initiative 未对证明进行标准化。
注释包含有关镜像的任意元数据。注释作为标签附加到镜像配置，或在 image index 或 manifest 上作为 properties 进行分配。

添加注释

您可以在构建时或创建镜像时向镜像添加注释 manifest 或 index。

注意
Docker Engine 镜像存储不支持加载镜像附注。要使用 annotation 构建，请确保直接推送镜像到 registry，使用 CLI 标志或 registry exporter 进行注册。--push

要在命令行上指定注释，请使用命令的标志：--annotationdocker build

$ docker build --push --annotation "foo=bar" .

如果您使用的是 Bake，则可以使用该属性为给定目标指定注释：annotations

target "default" {
  output = ["type=registry"]
  annotations = ["foo=bar"]
}

有关如何向使用 GitHub Actions 构建的镜像添加注释的示例，请参阅使用 GitHub Actions 添加镜像注释

您还可以向使用创建的镜像添加注释。此命令仅支持向索引添加 annotation 或清单描述符，请参阅 CLI 参考。docker buildx imagetools create

要查看镜像索引上的注释，请使用命令。这将显示索引和描述符的所有注释（对清单的引用）的 Fragment S 的 Flows Package。以下示例显示了描述符上的注释和索引上的注释。docker buildx imagetools inspectorg.opencontainers.image.documentationorg.opencontainers.image.authors

$ docker buildx imagetools inspect <IMAGE> --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb",
      "size": 911,
      "annotations": {
        "org.opencontainers.image.documentation": "https://foo.example/docs",
      },
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
  ],
  "annotations": {
    "org.opencontainers.image.authors": "dvdksn"
  }
}

要检查清单上的注释，请使用命令并指定，其中是摘要清单中：docker buildx imagetools inspect<IMAGE>@<DIGEST><DIGEST>

$ docker buildx imagetools inspect <IMAGE>@sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:4368b6959a78b412efa083c5506c4887e251f1484ccc9f0af5c406d8f76ece1d",
    "size": 850
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:2c03dbb20264f09924f9eab176da44e5421e74a78b09531d3c63448a7baa7c59",
      "size": 3333033
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:4923ad480d60a548e9b334ca492fa547a3ce8879676685b6718b085de5aaf142",
      "size": 61887305
    }
  ],
  "annotations": {
    "index,manifest:org.opencontainers.image.vendor": "foocorp",
    "org.opencontainers.image.source": "https://git.example/foo.git",
  }
}

指定注释级别

默认情况下，注释会添加到镜像清单中。您可以指定级别（OCI 镜像组件）将标注附加到，方法是在 annotation 字符串中具有特殊类型声明：

$ docker build --annotation "<TYPE>:<KEY>=<VALUE>" .

支持以下类型：

manifest：对清单进行注释。
index：对根索引进行注释。
manifest-descriptor：对索引中的清单描述符进行注释。
index-descriptor：对镜像布局中的索引描述符进行注释。

例如，要构建一个镜像，并将注释附加到图片索引：foo=bar

$ docker build --tag <IMAGE> --push --annotation "index:foo=bar" .

请注意，构建必须生成您指定的组件，否则 build 将失败。例如，以下命令不起作用，因为导出器不生成索引：docker

$ docker build --output type=docker --annotation "index:foo=bar" .

同样，以下示例也不起作用，因为 buildx 在某些情况下默认会创建输出，例如当 provenance 证明被明确禁用：docker

$ docker build --provenance=false --annotation "index:foo=bar" .

可以指定类型（用逗号分隔）以添加注释多个级别。以下示例创建一个镜像，并在镜像索引和镜像清单上都有注释：foo=bar

$ docker build --tag <IMAGE> --push --annotation "index,manifest:foo=bar" .

您还可以在类型的方括号内指定 platform 限定符前缀，以仅注释与特定操作系统和架构匹配的组件。这以下示例仅将注释添加到清单中：foo=barlinux/amd64

$ docker build --tag <IMAGE> --push --annotation "manifest[linux/amd64]:foo=bar" .

参考资料：

附注

添加注释

检查注释

指定注释级别

相关信息