手动迁移到 Artifact Registry 中的 `gcr.io` 代码库

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

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

准备工作

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

   gcloud components update
   

2. 启用 Artifact Registry 和 Resource Manager API。 gcloud CLI 使用 Resource Manager API 检查是否具有所需的权限之一。

   运行以下命令：

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

3. 在开始过渡之前，先了解 Artifact Registry 的价格。

所需的角色

如需获得设置 gcr.io 代码库所需的权限，请让您的管理员为您授予以下 IAM 角色：

• 如需创建 Artifact Registry 制品库并授予对各个制品库的访问权限： Artifact Registry Administrator (roles/artifactregistry.admin) on the Google Cloud project
• 如需查看和管理应用于 Cloud Storage 存储分区的现有 Container Registry 配置，您需要拥有 Google Cloud 项目的 Storage Admin (roles/storage.admin) 角色 Storage Admin (roles/storage.admin) Google Cloud 项目
• 首次将映像推送到 gcr.io 主机名时，如需创建 gcr.io 代码库，请在 Google Cloud 项目中添加 Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) 角色。 Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) on the Google Cloud project
• 如需在项目级层授予代码库访问权限： Project IAM Admin (roles/resourcemanager.projectIamAdmin) on the Google Cloud project
• 如需列出组织中已启用的服务，您需要拥有以下权限： 组织的 Cloud Asset Viewer (roles/cloudasset.viewer) 角色

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

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

限制

以下限制适用于 Artifact Registry gcr.io 代码库：

• 从 Container Registry 转换时，您无法将 Container Registry 主机映射到其他项目中的 Artifact Registry 代码库。

• 每个 Container Registry 主机名仅映射到同一多区域位置中的一个相应 Artifact Registry gcr.io 代码库。

• gcr.io 代码库的名称是预定义的，您无法修改。

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

创建代码库

创建 gcr.io 代码库，以便您可以为用户配置访问权限，并在启用重定向之前将现有的 Container Registry 映像复制到 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 制品库位置	Artifact Registry 制品库名称
      gcr.io	us	gcr.io
      asia.gcr.io	asia	asia.gcr.io
      eu.gcr.io	europe	eu.gcr.io
      us.gcr.io	us	us.gcr.io

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

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

      • Google-managed encryption key - 使用 Google-owned and Google-managed encryption key加密代码库内容。
      • 客户管理的密钥 - 使用您通过 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 制品库位置	Artifact Registry 制品库名称
     gcr.io	us	gcr.io
     asia.gcr.io	asia	asia.gcr.io
     eu.gcr.io	europe	eu.gcr.io
     us.gcr.io	us	us.gcr.io

   • 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 Reader (roles/artifactregistry.reader)	Artifact Registry 制品库或 Google Cloud 项目
推送和拉取映像（读取和写入） 删除图片	Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)	Artifact Registry 制品库或 Google Cloud 项目
首次将映像推送到项目中的 gcr.io 主机名时，在 Artifact Registry 中创建 gcr.io 存储库。	Storage Admin (roles/storage.admin)	Artifact Registry Create-on-push Repository Administrator (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud 项目
创建、管理和删除代码库	Storage Admin (roles/storage.admin)	Artifact Registry Administrator (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

制品分析同时支持 Container Registry 和 Artifact Registry。这两个产品都使用相同的 Artifact Analysis API 来进行映像元数据和漏洞扫描，并使用相同的 Pub/Sub 主题来接收 Artifact Analysis 通知。

不过，只有在启用重定向时，才会发生以下操作：

• 自动扫描 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 流量重定向功能。

如果在启用重定向后遇到问题，您可以运行 gcloud artifacts settings disable-upgrade-redirection 命令将流量路由回 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 是您要更新的账号的电子邮件地址。 例如 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

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

Artifact Registry 开始启用重定向。

如需检查重定向的当前状态，请运行以下命令：

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 代码库的主机名，并且您拥有具有 artifactregistry.repositories.createOnPush 权限的角色，则 Artifact Registry 会创建该代码库。预定义角色“Create-on-push Writer”(artifactregistry.createOnPushWriter) 和“Create-on-push Repository Administrator”(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 存储桶，请执行以下操作：

gcloud storage rm gs://BUCKET-NAME --recursive

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 代码库。