管理容器元数据

本页介绍了如何将容器映像封装到容器中、将其上传到 Artifact Registry，以及管理以附件形式存储在 Artifact Registry 中的容器映像的元数据。

附件是 OCI 工件，只能存储在 Docker 格式的代码库中。

准备工作

  1. 如果您还没有，请创建 Docker 格式的标准代码库。
  2. （可选）为 Google Cloud CLI 命令配置默认值。

所需的角色

如需获得管理附件所需的权限，请让管理员向您授予代码库的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

设置 Oras（可选）

除了使用 gcloud CLI 之外，您还可以选择使用 Oras 创建、列出和下载附件。

  1. 安装 Oras 1.2 或更高版本。如需验证版本，请运行 oras version 命令。

  2. 配置 Oras 以通过 Artifact Registry 进行身份验证。

创建连接

您可以使用 gcloud CLI 或 Oras 创建附件。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

  • ATTACHMENT：附件的完全限定名称。例如，projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment。或者，只提供附件 ID 并使用 --location 和 --repository 标志。
  • TARGET：要附加的文件将引用的工件的完全限定版本名称或 Artifact Registry URI。您可以使用摘要或代码。例如 us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1。
  • TYPE：附件的 type 属性。此属性必须符合 artifactType 属性的 OCI 规范。
  • 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

使用 Oras 创建附件时，Artifact Registry 会生成一个随机 UUID 用作附件名称。

在运行命令之前，请先进行以下替换：

  • ARTIFACT_TYPE：附件的 artifactType。

  • IMAGE_URI：附件所引用的图片容器的 URI。

  • FILE：要作为附件中的元数据包含的本地文件。

  • MEDIA_TYPE：图层的 mediaType。

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

以下示例创建了一个附件，其中包含一个文件 hello-world.txt，该文件引用了通过 URI 和标记标识的容器映像 my-image：

  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

其中：

  • doc/example 用于定义附件的 artifactType 属性。

  • us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 是 URI，其中包含附件将引用的容器映像版本的标记。

  • hello-world.txt 是附件将用作其数据的本地文件。

  • application/vnd.me.hi 用于定义图层的 mediaType。

如需查看完整指南和更多示例，请参阅 oras attach 文档。

列表附件

一个容器映像可以有任意数量的引用它的附件。您可以使用 Google Cloud 控制台、gcloud CLI 或 Oras 列出附件。

控制台

  1. 在 Google Cloud 控制台中，打开代码库页面。

    打开“代码库”页面

  2. 点击代码库名称可查看代码库中的映像。

  3. 如需查看映像的版本，请点击映像名称。

  4. 点击相应的图片版本。

  5. 如需查看该版本的附件，请点击附件标签页。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

  • TARGET：您要为其列出附件的工件的完全限定版本名称或 Artifact Registry URI。您可以使用摘要或代码。例如 us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud artifacts attachments list \
    --target=TARGET

Windows (PowerShell)

gcloud artifacts attachments list `
    --target=TARGET

Windows (cmd.exe)

gcloud artifacts attachments list ^
    --target=TARGET
 如需了解详情，请参阅 gcloud artifacts attachments list 命令。

Oras

在运行该命令之前，请先进行以下替换：

  • IMAGE_URI：所列附件引用的目标图片的 URI。
oras discover --distribution-spec v1.1-referrers-api IMAGE_URI

以下示例列出了容器映像 my-image 的附件，该映像通过 URI 和标记进行标识：

oras discover --distribution-spec v1.1-referrers-api \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

其中：

  • v1.1-referrers-api 是使用的 Referrer API。如需了解详情，请参阅分发规范中的详细信息。

  • us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 是包含要为其列出附件的容器映像版本的标记的 URI。

如需查看完整指南和更多示例，请参阅 oras discover 文档。

下载附件

您可以使用 gcloud CLI 或 Oras 下载附件。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

  • ATTACHMENT：附件的完全限定名称。例如，projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment。或者，您也可以在此处仅提供附件 ID，并使用 --location 和 --repository 标志。
  • DESTINATION：本地文件系统中用于下载附件的路径。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows (PowerShell)

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows (cmd.exe)

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION
 除了提供 ATTACHMENT 之外，您还可以提供 --oci-version-name 标志，后跟附件的完整版本名称或工件注册表 URI。您可以使用摘要或代码。例如 projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123。

如需了解详情，请参阅 gcloud artifacts attachments download 命令。

Oras

在运行命令之前，请先进行以下替换：

  • DESTINATION：附件的目标目录。

  • ATTACHMENT_URI：要下载的附件的 URI。这是附件引用的图片容器的 URI，后跟附件的唯一 SHA。

oras pull -o DESTINATION ATTACHMENT_URI

以下示例下载了通过 URI 和摘要标识的附件：

oras pull -o . us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx

其中：

  • -o . 将当前目录命名为下载目的地。

  • us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx 是包含要下载的附件的摘要的图片 URI。

如需查看完整指南和更多示例，请参阅 oras pull 文档。

删除附件

您可以使用 Google Cloud 控制台或 gcloud CLI 直接删除附件。您可以通过删除相应附件所引用的容器映像来间接删除附件。

直接删除附件

您可以使用以下任一选项直接删除附件：

控制台

  1. 在 Google Cloud 控制台中，打开代码库页面。

    打开“代码库”页面

  2. 点击代码库名称可查看代码库中的映像。

  3. 点击映像名称即可查看该映像的版本。

  4. 点击要查看其附件的图片版本。

  5. 点击附件标签页可查看该版本的附件。

  6. 点击要删除的附件的摘要。

  7. 点击删除。

  8. 在确认对话框中，点击删除。

gcloud

在使用下面的命令数据之前，请先进行以下替换：

  • ATTACHMENT：附件的完全限定名称。例如，projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment。或者，您也可以在此处仅提供附件 ID，并使用 --location 和 --repository 标志。

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud artifacts attachments delete ATTACHMENT

Windows (PowerShell)

gcloud artifacts attachments delete ATTACHMENT

Windows (cmd.exe)

gcloud artifacts attachments delete ATTACHMENT
 如需了解详情，请参阅 gcloud artifacts attachments list 命令。

间接删除附件

如果删除容器映像，则所有引用的附件也会被删除。这适用于手动删除容器映像，也适用于清理政策导致的删除。