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

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

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

注意： Artifact Registry 管理员角色包含其他 Artifact Registry 预定义角色中的大多数权限，但不包含用于在首次推送到 gcr.io 仓库时创建 gcr.io 仓库的 artifactregistry.repositories.createOnPush 权限。

限制

Artifact Registry gcr.io 仓库存在以下限制：

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

  注意 ：您仍然可以从其他 Google Cloud 项目中拉取 gcr.io 代码库中的容器映像。

• 每个 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 project
创建、管理和删除代码库	Storage Admin (roles/storage.admin)	Artifact Registry Administrator (roles/artifactregistry.Admin)	Google Cloud project

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

服务的默认服务账号在项目级别具有自己的角色。 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 来获取映像元数据和进行漏洞扫描，以及使用相同的 Pub/Sub 主题来发送 Artifact Analysis 通知。

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

• 自动扫描 Artifact Registry 中的 gcr.io 仓库。
• 在 Pub/Sub 通知中添加了 gcr.io 代码库活动。

您可以继续使用 gcloud container images 命令列出与 gcr.io 映像路径相关的备注和出现情况。

Container Registry

Artifact Registry

使用按需扫描功能在搭载受支持操作系统的映像中扫描操作系统和语言包漏洞。自动扫描仅返回操作系统漏洞信息。 详细了解扫描类型。 按需扫描 Google Cloud CLI 命令 gcloud artifacts docker images scan 可扫描本地映像或 Container Registry 中的映像，查找漏洞。 Google Cloud CLI 命令 gcloud artifacts docker images list-vulnerabilities 会返回漏洞扫描结果。 扫描 Container Registry 中采用 受支持的操作系统的映像，返回其操作系统和语言包漏洞信息。 自动扫描 Google Cloud CLI 命令 gcloud container images 包含用于查看扫描结果（包括漏洞和其他元数据）的标志。 扫描仅会针对使用 受支持的操作系统的 Container Registry 中的映像返回操作系统漏洞信息。

通过按需扫描和自动扫描来扫描操作系统和语言包漏洞。 详细了解扫描类型。 按需扫描 Google Cloud CLI 命令 gcloud artifacts docker images scan 可扫描本地映像或 Artifact Registry 中的映像，查找漏洞。 Google Cloud CLI 命令 gcloud artifacts docker images list-vulnerabilities 会返回漏洞扫描结果。 扫描会针对 Artifact Registry 中采用 受支持的操作系统的映像返回操作系统和语言包漏洞信息。 自动扫描 Google Cloud CLI 命令 gcloud artifacts docker images 包含用于查看扫描结果（包括漏洞和其他元数据）的标志。 扫描会针对 Artifact Registry 中采用 受支持的操作系统的映像返回操作系统漏洞信息，并针对受支持和不受支持的操作系统返回语言包漏洞信息。

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 管理员和 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 是您要更新的账号的电子邮件地址。例如 [e-mail]

验证项目设置

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

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

系统会重定向所有指向 gcr.io、asia.gcr.io、eu.gcr.io 和 us.gcr.io 的流量，即使您未为所有 Container Registry 主机名创建 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 存储分区，请执行以下操作：

控制台

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. 如需确认删除，请输入存储分区名称，然后点击删除。

gcloud

如果您要批量删除存储分区中的十万个或更多图片，请避免使用 gcloud CLI，因为删除过程需要很长时间才能完成。请改用 Google Cloud 控制台执行此操作。如需了解详情，请参阅批量删除 Cloud Storage 对象。

如需删除存储分区，请使用带有 --recursive 标志的 gcloud storage rm 命令。

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

将 BUCKET-NAME 替换为容器注册表存储分区名称。在存储分区名称中，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

响应如下例所示：

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

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

后续步骤

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