本頁面由 Cloud Translation API 翻譯而成。

將構件中繼資料儲存在附件中

本頁說明如何將儲存在 Artifact Registry 中的構件相關中繼資料儲存為附件。

附件中儲存的中繼資料可能包括構件安全漏洞、建構來源資訊、套件內容、認證、安全漏洞評估、軟體物料清單 (SBOM) 等資訊。政策系統可以使用 Artifact Registry 附件中儲存的資訊，使用者也可以檢查這些資訊，確保符合規範。

如要進一步瞭解如何使用附件，請參閱管理含有附件的中繼資料。

事前準備

如果沒有，請建立標準模式存放區。
(選用) 設定 Google Cloud CLI 指令的預設值。

必要的角色

如要取得建立附件所需的權限，請要求管理員授予您存放區的 Artifact Registry 寫入者 (roles/artifactregistry.writer) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

建立連結

如果是 Docker 存放區，附件必須是 OCI 構件。如果不是 Docker 格式，附件可以是任何檔案類型。

您可以使用 gcloud CLI 或 Oras，在 Docker 格式的存放區中建立附件。

如要建立附件，請完成下列步驟：

gcloud (所有格式)

使用下方的任何指令資料之前，請先替換以下項目：

ATTACHMENT：附件的完整名稱，例如 projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment。或者，您也可以只提供附件 ID，並使用 --location 和 --repository 標記。
TARGET：完整版本名稱。如果是 Docker 映像檔，您也可以使用附件參照的構件 Artifact Registry URI。在 URI 中，您可以使用摘要，或 Docker 映像檔的標記，例如 us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1。
TYPE：附件的 type 屬性。如果是 Docker 映像檔，type 必須符合 OCI 規格的 artifactType 屬性。
ATTACHMENT_NAMESPACE：附件專屬變數，可識別附件資料來源，例如 example.com。
FILES：以半形逗號分隔的本機檔案清單，這些檔案會加入附件。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud artifacts attachments create ATTACHMENT \
    --target=TARGET \
    --attachment-type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

Windows (PowerShell)

gcloud artifacts attachments create ATTACHMENT `
    --target=TARGET `
    --attachment-type=TYPE `
    --attachment-namespace=ATTACHMENT_NAMESPACE `
    --files=FILES

Windows (cmd.exe)

gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --attachment-type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES

gcloud artifacts attachments create

Oras (僅限 Docker)

使用 Oras 建立附件時，Artifact Registry 會產生隨機 UUID，做為附件名稱。

使用 Oras 前，請先完成下列步驟：

安裝 Oras 1.2 以上版本。如要驗證版本，請執行 oras version 指令。
設定 Oras，以便向 Artifact Registry 驗證。

執行指令前，請進行下列替換：

ARTIFACT_TYPE：附件的artifactType。
IMAGE_URI：附件參照的圖片容器 URI。
FILE：要加入附件中繼資料的本機檔案。
MEDIA_TYPE：圖層的 mediaType。

  oras attach --artifact-type ARTIFACT_TYPE IMAGE_URI FILE:MEDIA_TYPE

以下範例會建立附件，其中包含參照容器映像檔 (my-image) 的檔案 (hello-world.txt)，並以 URI 和標記識別：

  oras attach --artifact-type doc/example \
  us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

其中：

定義附件的 artifactType 屬性。doc/example
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 是 URI，包括附件參照的容器映像檔版本標記。
hello-world.txt 是附件將做為資料的本機檔案。
application/vnd.me.hi 定義圖層的 mediaType。

如需完整指南和更多範例，請參閱 oras attach 說明文件。

使用資源清理政策管理附件

如果刪除 Docker 存放區附件 (包括建構出處) 所附加的構件，這些附件也會一併刪除。如果您使用清除政策從存放區刪除映像檔，系統預設也會一併刪除這些映像檔的附件。

為確保您想保留的附件不會因清理政策而遭到刪除，您可以將標記指派給含有想保留附件的圖片。接著，您可以設定清除政策，保留含有這些標記的圖片。舉例來說，您可以將 production-signed 標記指派給附有建構出處的圖片。

後續步驟

管理構件中繼資料。
瞭解如何產生及儲存容器映像檔的 SBOM。