注解

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

注解与 labels 类似，在某种程度上也有重叠。它们的目的相同：为资源附加元数据。一般来说，可以将注解与 labels 的区别理解如下：

注解描述 OCI 镜像组件，例如 manifests、indexes 和 descriptors。
Labels 描述 Docker 资源，例如镜像、容器、网络和卷。

OCI 镜像规范定义了注解的格式以及一组预定义的注解键。遵循规定的标准可确保镜像的元数据能够被 Docker Scout 等工具自动且一致地呈现。

注解与证明（attestations）不可混淆

证明包含关于镜像如何构建以及包含哪些内容的信息。证明作为单独的 manifest 附加在镜像 index 上。证明并未由 Open Container Initiative 标准化。
注解包含关于镜像的任意元数据。注解可以作为 labels 附加到镜像config上，也可以作为属性附加到镜像 index 或 manifest 上。

添加注解

你可以在构建时，或在创建镜像 manifest 或 index 时，向镜像添加注解。

注意
Docker Engine 镜像存储不支持加载带有注解的镜像。要构建带有注解的镜像，请确保使用 --push CLI 标志或 registry exporter 将镜像直接推送到镜像仓库。

要在命令行上指定注解，请在 docker build 命令中使用 --annotation 标志

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

如果你使用 Bake，可以使用 annotations 属性为给定的 target 指定注解

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

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

你还可以使用 docker buildx imagetools create 创建的镜像添加注解。此命令仅支持向 index 或 manifest descriptors 添加注解，详情请参见 CLI 参考。

要查看镜像 index 上的注解，请使用 docker buildx imagetools inspect 命令。这将显示 index 及其包含的 descriptors（指向 manifests 的引用）的任何注解。以下示例显示 descriptor 上的 org.opencontainers.image.documentation 注解以及 index 上的 org.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"
  }
}

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

$ 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",
  }
}

指定注解级别

默认情况下，注解会添加到镜像 manifest 中。你可以通过在注解字符串前加上特殊的类型声明，指定要将注解附加到哪个级别（OCI 镜像组件）

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

支持以下类型

manifest：为 manifests 添加注解。
index：为根 index 添加注解。
manifest-descriptor：为 index 中的 manifest descriptors 添加注解。
index-descriptor：为镜像 layout 中的 index descriptor 添加注解。

例如，构建一个带有附加到镜像 index 的注解 foo=bar 的镜像

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

请注意，构建必须生成你指定的组件，否则构建将失败。例如，以下操作不起作用，因为 docker exporter 不会生成 index

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

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

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

可以指定用逗号分隔的类型，将注解添加到多个级别。以下示例创建一个镜像，其中注解 foo=bar 同时存在于镜像 index 和镜像 manifest 上

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

你还可以在类型前缀的方括号内指定平台限定符，仅为与特定操作系统和架构匹配的组件添加注解。以下示例仅为 linux/amd64 manifest 添加 foo=bar 注解

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

参考信息

注解

添加注解

检查注解

指定注解级别

相关信息