注解

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

注解与标签相似，在某种程度上与标签重叠。标签。两者都具有相同的目的：将元数据附加到资源上。作为一个总体原则，你可以这样思考注解和标签之间的区别：

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

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

注解与证明不应混淆：

断言包含有关如何构建镜像以及镜像包含内容的信息。断言作为单独的清单附加在镜像索引上。断言未由开放容器计划标准化。
注释包含有关镜像的任意元数据。注释附加到镜像的配置上作为标签，或在镜像索引或清单上作为属性。

添加注释

您可以在构建时为镜像添加注释，或在创建镜像清单或索引时添加。

注意
Docker Engine 镜像存储不支持加载带注解的镜像。若要使用注解构建，请确保直接将镜像推送到注册表，使用 --push CLI 标志或注册表导出器。

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

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

如果你使用的是 Bake，你可以使用 annotations 属性为给定的目标指定注解：

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

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

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

检查注释

要查看 镜像索引 上的注释，请使用 docker buildx imagetools inspect 命令。这会显示索引及其包含的描述符（指向清单的引用）上的任何注释。以下示例显示了描述符上的一个 org.opencontainers.image.documentation 注释，以及索引上的一个 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"
  }
}

要检查清单上的注释，请使用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镜像组件）：

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

以下类型受支持：

manifest: 为清单添加注释。
index: 为根索引添加注释。
manifest-descriptor: 为索引中的清单描述符添加注释。
index-descriptor: 为镜像布局中的索引描述符添加注释。

例如，要构建一个带有注解 foo=bar 的镜像索引：

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

请注意，构建必须生成您指定的组件，否则构建将失败。例如，以下内容无法正常工作，因为 docker 导出器不会生成索引：

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

同样，以下示例也无法正常工作，因为在某些情况下（例如，明确禁用来源证明时），buildx 会默认生成一个 docker 输出：

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

可以指定用逗号分隔的类型，将注解添加到多个级别。以下示例在镜像索引和镜像清单上都创建了带有注解 foo=bar 的镜像：

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

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

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

参考信息：

注解

添加注释

检查注释

指定注解级别

相关信息