註解

目錄

註解為映象提供描述性元資料。使用註解來記錄任意資訊並將其附加到您的映象中，這有助於消費者和工具理解映象的來源、內容以及如何使用它。

註解與標籤類似，並在某種程度上與標籤重疊。兩者都服務於相同的目的：將元資料附加到資源。通常，您可以這樣理解註解和標籤之間的區別：

  • 註解描述 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" .

相關文章

參考資訊