註釋

目錄

註釋提供映像檔的描述性中繼資料。使用註釋可以記錄任意資訊並將其附加到您的映像檔，這有助於使用者和工具了解映像檔的來源、內容以及使用方法。

註釋與標籤類似，並且在某種程度上與標籤重疊。兩者都具有相同的用途：將中繼資料附加到資源。作為一般原則，您可以將註釋和標籤之間的差異視為如下：

  • 註釋描述 OCI 映像檔組件，例如資訊清單索引描述元規格證明混淆。

    • 證明包含有關映像檔如何建置及其包含內容的資訊。證明作為單獨的資訊清單附加在映像檔索引上。證明未由開放容器倡議 (Open Container Initiative) 標準化。
    • 註釋包含有關映像檔的任意中繼資料。註釋以標籤的形式附加到映像檔設定新增註釋

      您可以在建置時或建立映像檔資訊清單或索引時新增註釋。

      **注意**

      Docker Engine 映像檔存放區不支援載入具有註釋的映像檔。要使用註釋進行建置，請確保使用 --push CLI 旗標或registry exporter將映像檔直接推送到 registry。

      若要在命令列上指定註釋，請在 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" .

      相關文章

      參考資訊