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

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

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

如果您想使用以下命令在 Artifact Registry 中创建 gcr.io 代码库 客户管理的加密密钥 (CMEK)，则 完成准备工作中的步骤，然后 请参阅手动创建代码库中的说明。

准备工作

  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 的价格 您就会开始转换。

所需的角色

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

  • 如需创建 Artifact Registry 代码库并授予对各个代码库的访问权限，请执行以下操作： Artifact Registry 管理员 (roles/artifactregistry.admin) Google Cloud 项目
  • 如需查看和管理应用于 Cloud Storage 存储分区的现有 Container Registry 配置，请执行以下操作： Storage Admin (roles/storage.admin) Google Cloud 项目
  • 如需在首次将映像推送到 gcr.io 主机名时创建 gcr.io 代码库，请执行以下操作： Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) Google Cloud 项目
  • 如需在项目级授予代码库访问权限，请执行以下操作： Project IAM Admin (roles/resourcemanager.projectIamAdmin) Google Cloud 项目
  • 要列出组织中已启用的服务，请执行以下操作： 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 网域。由于标准代码库不支持 gcr.io 网域，因此这种过渡方法需要对现有的自动化操作和工作流程进行更多更改。请参阅 [选择转换选项][选项] 了解详情 功能差异

创建代码库

创建 gcr.io 代码库，以便为您的用户配置访问权限，以及 先将现有 Container Registry 映像复制到 Artifact Registry，然后再启用 重定向。

手动创建代码库

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

如需手动创建 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 美国 gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io 欧洲 eu.gcr.io
      us.gcr.io 美国 us.gcr.io

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

    7. 在加密部分，为 代码库

      • Google 管理的密钥 - 使用 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 仓库位置 Artifact Registry 代码库名称
      gcr.io 美国 gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io 欧洲 eu.gcr.io
      us.gcr.io 美国 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 存储桶。

在 v3 发布之前就已存在的基本角色“Owner”“Editor”和“Viewer” IAM 拥有 对存储分区的有限访问权限。 它们本身并不具有名称所授予的 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 存储库。 存储管理员
(roles/storage.admin)		 Artifact Registry Create-on-push Repository Administrator
(roles/artifactregistry.createOnPushRepoAdmin)		 Google Cloud 项目
创建、管理和删除代码库 存储管理员
(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 服务。

请参阅 服务代理角色参考，详细了解相关权限 Service Agent 角色。

自定义角色

您可以借助角色映射表来决定 根据访问权限级别向用户或服务账号授予的角色 所需的资源

如需了解如何授予 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 container images包含用于查看扫描结果的标志 包括漏洞和其他元数据。
  • 扫描仅返回以下环境中映像的操作系统漏洞信息 Container Registry 支持的操作系统。
通过按需和按需扫描，扫描操作系统和语言包漏洞 自动扫描。 详细了解 扫描。
按需扫描
自动扫描
  • Google Cloud CLI 命令 gcloud 工件 docker images 包含用于查看扫描结果的标志， 包括漏洞和其他元数据。
  • 扫描会针对 Artifact Registry 中采用受支持的操作系统的映像返回操作系统漏洞信息，并针对受支持和不受支持的操作系统返回语言包漏洞信息。

Pub/Sub 通知

Artifact Registry 会将更改发布到与 Container Registry 相同的 gcr 主题。如果您已经在使用 具有 Container Registry 的 Pub/Sub Artifact 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代码库 启用重定向时，我们建议您先创建这些重定向， 在启用重定向之前可以执行以下操作：

开启重定向

要为 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的所有流量均为 已重定向，即使您没有为所有代码库创建 gcr.io 代码库 Container Registry 主机名。如果您将映像推送到没有相应 Artifact Registry 代码库的主机名，并且您拥有具有 artifactregistry.repositories.createOnPush 权限的角色，Artifact Registry 会创建该代码库。预定义角色 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 映像，请删除相应 Cloud Storage 每个 Container Registry 主机名的存储分区

如需删除每个 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 对象。

如需删除存储桶，请使用 gcloud storage rm 并附加 --recursive 标志。

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/...

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

后续步骤