设置支持 gcr.io 的代码库

本文档介绍了如何在 Artifact Registry 中手动设置 gcr.io 代码库。

我们建议您使用我们的自动迁移工具过渡到 Artifact Registry 中的 gcr.io 代码库。

如果您要使用客户管理的加密密钥 (CMEK) 在 Artifact Registry 中创建 gcr.io 代码库，请完成准备工作中的步骤，然后按照手动创建代码库中的说明操作。

准备工作

1. 安装 Google Cloud CLI（如果尚未安装）。对于现有安装，请运行以下命令，将组件更新到最新版本：

   gcloud components update
   

2. 启用 Artifact Registry API 和 Resource Manager API。gcloud CLI 使用 Resource Manager API 检查是否具备其中一项必需的权限。

   运行以下命令：

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       artifactregistry.googleapis.com
   

3. 在开始转换之前，请了解 Artifact Registry 的pricing。

所需的角色

如需获取设置“gcr.io”代码库所需的权限，请让管理员授予您 Google Cloud 项目的以下 IAM 角色：

• 如需创建 Artifact Registry 代码库并授予对各个代码库的访问权限，请执行以下操作： Artifact Registry Administrator (roles/artifactregistry.admin)
• 如需查看和管理应用于 Cloud Storage 存储分区的现有 Container Registry 配置，请执行以下操作： Storage Admin (roles/storage.admin)
• 如需在首次将映像推送到 gcr.io 主机名时创建 gcr.io 代码库，请使用以下代码：Artifact Registry Create-on-push 写入者 (roles/artifactregistry.createOnPushWriter)
• 如需在项目级授予代码库访问权限，请执行以下操作： Project IAM Admin (roles/resourcemanager.projectIamAdmin) 或包含等效权限的角色，例如 Folder Admin (roles/resourcemanager.folderAdmin) 或 Organization Admin (roles/resourcemanager.organizationAdmin)

如需详细了解如何授予角色，请参阅管理访问权限。

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

限制

以下限制适用于支持 gcr.io 网域的代码库：

• 您无法将 Container Registry 主机映射到其他项目中的 Artifact Registry 代码库。
• 每个 Container Registry 主机名仅映射到同一多区域位置中一个对应的 Artifact Registry gcr.io 代码库。
• gcr.io 代码库的名称是预定义的，您无法修改它们。

如果您需要更好地控制代码库的位置，可以改用 Artifact Registry pkg.dev 网域中的标准代码库。由于标准代码库不支持 gcr.io 网域，因此这种过渡方法需要对现有的自动化功能和工作流进行更多更改。如需了解功能差异，请参阅选择转换选项。

创建代码库

创建 gcr.io 代码库，以便为用户配置访问权限，并在启用重定向之前将现有 Container Registry 映像复制到 Artifact Registry。

快速创建代码库

以下步骤将创建使用 Google 管理的加密密钥加密的 gcr.io 代码库。如果要使用客户管理的加密密钥 (CMEK)，则必须手动创建代码库。

如需创建 gcr.io 代码库，请执行以下操作：

1. 打开 Google Cloud 控制台中的制品库页面。

   打开“代码库”页面

   页面上，横幅会显示消息 You have gcr.io repositories in Container Registry。

   打开“设置”页面

2. 在横幅中，点击创建 gcr.io 代码库。

   此时会打开创建 gcr.io 代码库面板。复制映像部分列出了将创建的每个代码库的完全限定名称。如果您想在启用重定向之前从 Container Registry 中复制映像，则需要这些代码库名称。

3. 点击创建。

Artifact Registry 会为所有 Container Registry 主机名创建 gcr.io 代码库：

如需查看代码库的 Artifact Registry 网址，请将指针悬停在代码库名称旁边的警告图标 () 上。

在将流量重定向到新代码库之前，您需要确保现有的自动化操作可以访问该代码库。下一步是配置权限以授予对代码库的访问权限。

手动创建代码库

如果要使用客户管理的加密密钥 (CMEK) 加密代码库内容，或者您的 Google Cloud 组织中存在位置限制阻止在特定位置创建新资源的位置限制，请手动创建 gcr.io 代码库。

如需手动创建 gcr.io 代码库，请执行以下操作：

1. 如果您使用的是 CMEK，请创建要用于此代码库的密钥，并授予使用该密钥的权限。请参阅启用客户管理的加密密钥。

2. 添加代码库。

   控制台

   1. 打开 Google Cloud 控制台中的制品库页面。

      打开“代码库”页面

   2. 点击创建代码库。

   3. 指定代码库名称。

      Container Registry 主机名	Artifact Registry 代码库名称
      gcr.io	gcr.io
      asia.gcr.io	asia.gcr.io
      eu.gcr.io	eu.gcr.io
      us.gcr.io	us.gcr.io

   4. 将 Docker 指定为代码库格式。

   5. 在位置类型下，为代码库指定多区域：

      Container Registry 主机名	Artifact Registry 代码库位置
      gcr.io	us
      asia.gcr.io	asia
      eu.gcr.io	europe
      us.gcr.io	us

   6. 为代码库添加说明。请勿包含敏感数据，因为代码库说明未加密。

   7. 在加密部分中，选择代码库的加密机制。

      • Google 管理的密钥 - 使用 Google 管理的加密密钥来加密代码库内容。
      • 客户管理的密钥 - 使用您通过 Cloud Key Management Service 控制的密钥来加密代码库内容。如需查看密钥设置说明，请参阅为代码库设置 CMEK。

   8. 点击创建。

   gcloud

   运行以下命令创建新代码库。

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=docker \
       --location=LOCATION \
       --description=DESCRIPTION \
       --kms-key=KMS-KEY
   

   替换以下值：

   • REPOSITORY 是代码库的名称。

     Container Registry 主机名	Artifact Registry 代码库名称
     gcr.io	gcr.io
     asia.gcr.io	asia.gcr.io
     eu.gcr.io	eu.gcr.io
     us.gcr.io	us.gcr.io

   • LOCATION 是代码库的多区域：

     Container Registry 主机名	Artifact Registry 代码库位置
     gcr.io	us
     asia.gcr.io	asia
     eu.gcr.io	europe
     us.gcr.io	us

   • DESCRIPTION 是代码库的说明。请勿包含敏感数据，因为代码库说明未加密。

   • 如果您使用客户管理的加密密钥来加密代码库内容，则 KMS-KEY 是 Cloud KMS 加密密钥的完整路径。路径的格式为：

     projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

     替换以下值：

     • KMS-PROJECT 是存储密钥的项目。
     • KMS-LOCATION 是密钥的位置。
     • KEY-RING 是密钥环的名称。
     • KEY 是密钥的名称。

   您可以通过使用以下命令列出代码库，确认代码库已创建：

   gcloud artifacts repositories list
   

在将流量重定向到新代码库之前，您需要确保现有的自动化操作可以访问该代码库。下一步是配置权限以授予对代码库的访问权限。

向代码库授予权限

Container Registry 使用 Cloud Storage 角色来控制访问权限。 Artifact Registry 有自己的 IAM 角色，这些角色比 Container Registry 更清晰地将读取、写入和代码库管理员角色分开。

如需快速将针对存储分区授予的现有权限映射到建议的 Artifact Registry 角色，请使用角色映射工具。

或者，您也可以使用 Google Cloud 控制台查看有权访问存储分区的主账号列表。

1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 点击要查看的注册表主机的存储桶。 在存储桶名称中，PROJECT-ID 是您的 Google Cloud 项目 ID。

   • gcr.io: artifacts.PROJECT-ID.appspot.com
   • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
   • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
   • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

3. 点击权限标签页。

4. 在“权限”标签中，点击按角色查看子标签。

5. 展开某个角色以查看拥有该角色的主账号。

该列表包含直接在存储桶中授予的 IAM 角色以及从父项目继承的角色。根据角色，您可以选择要授予的最合适的 Artifact Registry 角色。

Cloud Storage 和基本角色

向当前访问 Container Registry 的用户和服务帐号授予对 Artifact Registry 代码库的访问权限。对于从父项目继承的 Cloud Storage 角色，您应验证主帐号当前使用 Container Registry。某些主账号可能只访问与 Container Registry 无关的其他 Cloud Storage 存储分区。

在 IAM 之前存在的基本角色 Owner、Editor 和 Viewer 对存储分区的访问权限有限。它们本身不会授予其名称所暗示的对 Cloud Storage 资源的所有访问权限，并且为其他 Google Cloud 服务提供额外的权限。验证哪些用户和服务帐号需要访问 Artifact Registry，并使用角色映射表来帮助您授予适当的角色（如果 Artifact Registry 访问权限合适）。

下表根据预定义 Cloud Storage 角色为 Container Registry 访问权限授予的权限映射了 Artifact Registry 角色。

所需的访问权限	当前角色	Artifact Registry 角色	在何处授予角色
仅拉取映像（只读）	Storage Object Viewer (roles/storage.objectViewer)	Artifact Registry 读取者 (roles/artifactregistry.reader)	Artifact Registry 代码库或 Google Cloud 项目
推送和拉取映像（读取和写入） 删除图片	存储空间旧存储分区写入者 (roles/storage.legacyBucketWriter)	Artifact Registry 代码库管理员 (roles/artifactregistry.repoAdmin)	Artifact Registry 代码库或 Google Cloud 项目
首次将映像推送到项目中的 gcr.io 主机名时，在 Artifact Registry 中创建 gcr.io 代码库。	Storage Admin (roles/storage.admin)	Artifact Registry Create-on-push 代码库管理员 (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud 项目
创建、管理和删除代码库	Storage Admin (roles/storage.admin)	Artifact Registry 管理员 (roles/artifactregistry.Admin)	Google Cloud 项目

从项目继承的服务代理角色

Google Cloud 服务的默认服务帐号具有自己的在项目级授予的角色。例如，Cloud Run 的服务代理具有 Cloud Run Service Agent 角色。

在大多数情况下，这些服务代理角色包含 Container Registry 和 Artifact Registry 的等效默认权限，如果您在现有 Container Registry 服务所在的项目中运行 Artifact Registry，则无需执行任何其他更改。

如需详细了解服务代理角色中的权限，请参阅服务代理角色参考文档。

自定义角色

使用角色映射表，可帮助您根据用户或服务帐号所需的访问权限级别，确定要向其授予的角色。

如需了解如何授予 Artifact Registry 角色，请参阅配置角色和权限。

从 Container Registry 复制容器

我们建议您使用我们的自动迁移工具将映像从 Container Registry 复制到 Artifact Registry。

如果要使用其他工具复制映像，请参阅从 Container Registry 复制映像

设置其他功能

本部分介绍您可能已在 Container Registry 中设置的其他功能的配置。

Artifact Analysis

Artifact Analysis 支持 Container Registry 和 Artifact Registry。这两种产品针对映像元数据和漏洞扫描使用相同的 Artifact Analysis API，并针对 Artifact Analysis 通知使用相同的 Pub/Sub 主题。

不过，只有在启用重定向后，才会执行以下操作：

• 自动扫描 Artifact Registry 中的 gcr.io 代码库。
• Pub/Sub 通知中包含 gcr.io 代码库活动。

您可以继续使用 gcloud container images 命令列出与 gcr.io 映像路径关联的备注和发生实例。

Pub/Sub 通知

Artifact Registry 会将更改发布到与 Container Registry 相同的 gcr 主题。如果您已在与 Artifact Registry 相同的项目中将 Pub/Sub 与 Container Registry 搭配使用，则无需进行其他配置。但是，在您启用重定向之前，Artifact Registry 无法发布 gcr.io 代码库的消息。

如果您在单个项目中设置 Artifact Registry，则 gcr 主题可能不存在。如需查看设置说明，请参阅配置 Pub/Sub 通知。

启用 gcr.io 流量的重定向

创建 gcr.io 代码库并为第三方客户端配置权限和身份验证后，您便可以启用 gcr.io 流量的重定向。

如果您在启用重定向后遇到问题，可以将流量路由回 Container Registry，然后在解决问题后再次启用重定向。

验证权限以启用重定向

如需启用重定向，您必须在项目级别拥有以下权限：

• artifactregistry.projectsettings.update：更新 Artifact Registry 项目设置的权限。此权限属于 Artifact Registry Administrator 角色 (roles/artifactregistry.admin)。
• storage.buckets.update - 拥有更新整个项目的存储分区的权限。此权限是 Storage Admin 角色 (roles/storage.admin) 中的权限。

如果您没有这些权限，请让管理员在项目级别授予这些权限。

以下命令可向项目授予 Artifact Registry Administrator 和 Storage Admin 角色。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

替换以下值：

• PROJECT_ID 是 Google Cloud 项目 ID。
• PRINCIPAL 是要更新的帐号的电子邮件地址。例如 user:my-user@example.com

验证项目设置

如需验证项目设置，请运行以下命令：

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

Artifact Registry 会检查映射到 Container Registry 主机名的代码库。

虽然在您启用重定向时，Artifact Registry 可以为您创建缺失的 gcr.io 代码库，但我们建议您先创建这些代码库，以便在启用重定向之前执行以下操作：

• 配置代码库级权限
• 从 Container Registry 复制您仍要使用的映像
• 执行任何其他配置。

开启重定向

要为 gcr.io 流量启用重定向，请执行以下操作：

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

gcloud artifacts settings describe

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

即使您未为所有 Container Registry 主机名创建 gcr.io 代码库，系统也将重定向到 gcr.io、asia.gcr.io、eu.gcr.io 和 us.gcr.io 的所有流量。如果您将映像推送到没有相应 Artifact Registry 代码库的主机名，则 Artifact Registry 会创建具有 artifactregistry.repositories.createOnPush 权限的角色。Create-on-push Writer (artifactregistry.createOnPushWriter) 和 Create-on-push 代码库管理员 (artifactregistry.createOnPushRepoAdmin) 的预定义角色具有此权限。

启用重定向后，您可以测试自动化操作，并验证是否可以使用新的 gcr.io 代码库推送和拉取映像。

验证重定向

验证对 gcr.io 主机名发出的拉取请求和推送请求是否均有效。

1. 使用测试映像的 gcr.io 路径将其推送到您的某个 gcr.io 代码库。

   1. 使用 gcr.io 路径标记映像。例如，以下命令会将映像 local-image 标记为 us.gcr.io/my-project/test-image：

      docker tag local-image us.gcr.io/my-project/test-image
      

   2. 推送您标记的映像。例如，以下命令会推送映像 us.gcr.io/my-project/test-image：

      docker push us.gcr.io/my-project/test-image
      

2. 列出代码库中的映像以验证映像是否已成功上传。例如，如需列出 us.gcr.io/my-project 中的映像，请运行以下命令：

   gcloud container images list --repository=us.gcr.io/my-project
   

3. 使用 Container Registry 路径从代码库中拉取映像。例如，以下命令会拉取映像 us.gcr.io/my-project/test-image。

   docker pull us.gcr.io/my-project/test-image
   

完成此初始测试后，验证用于构建和部署映像的现有自动化功能是否按预期运行，包括：

• 启用重定向后，使用 Container Registry 的用户和服务帐号仍然可以推送、拉取和部署映像。
• 您的自动化操作只会将映像推送到现有代码库。
• 如果启用了 Artifact Analysis 漏洞扫描，则扫描可识别 gcr.io 代码库中存在漏洞的映像。
• 如果您使用 Binary Authorization，您的现有政策适用于从 gcr.io 代码库部署的映像。
• 已配置的 Pub/Sub 订阅包括有关 gcr.io 代码库更改的通知。

清理 Container Registry 映像

启用重定向后，用于删除 gcr.io 路径中映像的命令会删除相应 Artifact Registry gcr.io 代码库中的映像。用于删除 gcr.io 路径中映像的删除命令不会删除存储在 Container Registry 主机上的映像。

如需安全地移除所有 Container Registry 映像，请删除每个 Container Registry 主机名的 Cloud Storage 存储分区。

如需删除每个 Container Registry 存储桶，请执行以下操作：

gsutil rm -r gs://BUCKET-NAME

Removing gs://artifacts.my-project.appspot.com/...

如果其他 Google Cloud 服务也在同一 Google Cloud 项目中运行，请使 Container Registry API 保持启用状态。如果您尝试停用 Container Registry API，如果项目中启用了具有已配置依赖项的其他服务，Container Registry 会显示警告。停用 Container Registry API 后，系统会自动停用同一项目中配置了依赖项的所有服务，即使您当前没有将 Container Registry 与这些服务搭配使用，也是如此。

后续步骤

• 试用 Docker 快速入门。
• 了解 gcr.io 代码库。