转换为标准代码库

如果您目前使用 Container Registry 管理容器映像，本页面介绍了如何设置标准 Artifact Registry 代码库，以及使用代码库与使用 Container Registry 有何不同。

这些说明主要面向代码库管理员。如需了解构建、推送、拉取和部署映像的具体变化，请参阅以下信息：

准备工作

  1. 通过 Google Cloud 控制台或使用以下命令启用 Artifact Registry API：

    gcloud services enable artifactregistry.googleapis.com

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

    gcloud components update

  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)
  • 如需在项目级授予代码库访问权限，请执行以下操作： Project IAM Admin (roles/resourcemanager.projectIamAdmin) 或包含等效权限的角色，例如 Folder Admin (roles/resourcemanager.folderAdmin) 或 Organization Admin (roles/resourcemanager.organizationAdmin)

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

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

概览

标准代码库是支持所有功能的常规 Artifact Registry 代码库。

为简单起见，本页面中的说明假定 Container Registry 和 Artifact Registry 位于同一个 Google Cloud 项目中。向 Artifact Registry 过渡时，您可以继续使用这两项服务，以便逐步执行设置步骤并更新自动化。如果需要，您可以在单个项目中设置 Artifact Registry，并执行相同的总体步骤。

Artifact Registry 还提供 gcr.io 代码库。这些代码库可以将 gcr.io 流量从您现有的注册表重定向到相应的 Artifact Registry 代码库。它们在一定程度上向后兼容 Container Registry，但也存在一些功能限制。但是，如果您有大量使用 gcr.io 引用的工具配置、脚本或代码，则可能需要采用更具战术性的方法过渡到 Artifact Registry。请查看具有 gcr.io 网域支持的代码库的转换文档，以帮助您做出适当的决策。

过渡步骤

本指南将向您介绍如何完成以下步骤：

  1. 为容器创建 Docker 代码库。您必须先创建一个代码库，然后才能向其推送映像。
  2. 授予对代码库的权限。
  3. 配置身份验证，以便您能够连接新的代码库。
  4. 如果需要，从 Container Registry 中复制要在新代码库中使用的映像。
  5. 尝试推送和拉取容器。
  6. 尝试将映像部署到运行时环境。
  7. 配置其他功能。
  8. 转换完成后，清理 Container Registry 中的映像。

创建代码库

如果您之前从未在多区域位置推送过映像，Container Registry 会自动在多区域位置创建一个存储桶。

在 Artifact Registry 中，您必须先创建代码库，然后才能上传映像。创建代码库时，您必须指定以下各项：

  • 代码库格式。Artifact Registry 将容器存储在 Docker 代码库中。

  • 代码库的单区域或多区域位置。

    为 Artifact Registry 代码库选择位置时，请考虑这些代码库与其他基础架构和用户之间的邻近程度。如果您打算将映像从 Container Registry 复制到 Artifact Registry，则位置之间的区别可能会影响复制费用。

  • Cloud Key Management Service 密钥（如果您使用客户管理的加密密钥 (CMEK) 进行加密的话）。

    在 Container Registry 中，您将 Container Registry 存储桶配置为使用 CMEK。在 Artifact Registry 中，您在创建代码库时将代码库配置为使用 CMEK。如需详细了解如何将 CMEK 用于 Artifact Registry，请参阅启用 CMEK（客户管理的加密密钥）。

Container Registry 会在网域 gcr.io 上托管容器。Artifact Registry 会在网域 pkg.dev 上托管容器。

如需了解如何创建代码库（包括使用 CMEK 进行加密的代码库），请参阅创建代码库。

授予权限

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 角色可提供预定义的 Cloud Storage 角色所不具备的一些额外权限分离。

所需的访问权限 当前角色 Artifact Registry 角色 在何处授予角色
仅拉取映像（只读） Storage Object Viewer
(roles/storage.objectViewer)		 Artifact Registry 读取者
(roles/artifactregistry.reader)		 Artifact Registry 代码库或 Google Cloud 项目
推送和拉取映像（读取和写入） 存储空间旧存储分区写入者
(roles/storage.legacyBucketWriter)		 Artifact Registry 写入者
(roles/artifactregistry.writer)		 Artifact Registry 代码库或 Google Cloud 项目
推送、拉取和删除映像 存储空间旧存储分区写入者
(roles/storage.legacyBucketWriter)		 Artifact Registry 代码库管理员
(roles/artifactregistry.repoAdmin)		 Artifact Registry 代码库或 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 角色，请参阅配置角色和权限。

向代码库进行身份验证

Artifact Registry 支持与 Container Registry 使用相同的身份验证方法。

如果您使用的是 Docker 凭据帮助程序：

  • 您必须使用 2.0 或更高版本与 Artifact Registry 代码库进行交互。GitHub 中提供了独立版本。
  • 您必须使用打算使用的 Artifact Registry 位置配置凭据帮助程序。默认情况下，凭据帮助程序仅配置对 Container Registry 主机的访问权限。

如需详细了解如何设置身份验证，请参阅为 Docker 设置身份验证。

从 Container Registry 复制容器

如果 Container Registry 中存在您希望继续在 Artifact Registry 中使用的容器，您可以通过多种方法复制这些容器。如需了解详情，请参阅从 Container Registry 复制映像

推送和拉取映像

您在 Artifact Registry 中用于标记、推送和拉取映像的 Docker 命令类似于您在 Container Registry 中使用的命令。主要有两个区别：

  • Artifact Registry Docker 代码库的主机名包含位置前缀，后跟 -docker.pkg.dev。例如 australia-southeast1-docker.pkg.dev、europe-north1-docker.pkg.dev 和 europe-docker.pkg.dev。
  • 由于 Artifact Registry 支持在单个项目中使用多个 Docker 代码库，因此您必须在命令中指定代码库名称。

例如，在 Container Registry 中，此命令会将映像 my-image 推送到项目 my-project 中的注册表 eu.gcr.io。

docker push eu.gcr.io/my-project/my-image

在 Artifact Registry 中，此命令会将映像 my-image 推送到代码库 my-repo 中的区域代码库 europe-north1-docker.pkg.dev 以及推送到项目 my-project。

docker push europe-north1-docker.pkg.dev/my-project/my-repo/my-image

如需详细了解如何在 Artifact Registry 中推送和拉取映像，请参阅推送和拉取映像。

部署映像

常见 Google Cloud 集成的服务帐号配置了同一项目中的代码库的默认权限。

通常情况下，使用 Cloud Build 构建映像并将其推送到代码库的运作方式与 Container Registry 中的运作方式相同。在 Artifact Registry 中，主要区别在于目标代码库必须存在，您才能将映像推送到其中（包括您要推送的第一个映像）。

请务必在运行用于推送映像的命令（包括 Docker 命令 docker push 和 Cloud Build 命令 gcloud builds submit）之前先创建所需的代码库。

Cloud Build 构建器仍托管在 gcr.io 上。如需了解详情，请参阅与 Cloud Build 集成。

其他功能

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

Artifact Analysis

Artifact Analysis 支持 Container Registry 和 Artifact Registry。 这两个产品都包含在 Artifact Analysis 文档中。

  • 这两种产品使用相同的 Artifact Analysis API。当您在 Container Registry 或 Artifact Registry 中启用 Artifact Analysis API 时，这两个产品都会启用这些 API。
  • 这两种产品都针对 Artifact Analysis 通知使用相同的 Pub/Sub 主题。
  • 您可以继续使用 gcloud container images 命令列出与 gcr.io 映像路径关联的备注和发生实例。
Container Registry Artifact Registry
在具有受支持操作系统的映像中通过按需扫描扫描操作系统和语言包漏洞。自动扫描只会返回操作系统漏洞信息。详细了解扫描类型。
按需扫描
自动扫描
  • Google Cloud CLI 命令 gcloud container images 包含用于查看扫描结果（包括漏洞和其他元数据）的标志。
  • 扫描操作仅会为 Container Registry 中采用 受支持的操作系统的映像返回操作系统漏洞信息。
 通过按需扫描和自动扫描，扫描操作系统和语言包漏洞。详细了解扫描类型。
按需扫描
自动扫描
  • Google Cloud CLI 命令 gcloudartifact docker images 包含用于查看扫描结果（包括漏洞和其他元数据）的标志。
  • 扫描会返回包含 受支持操作系统的 Artifact Registry 映像的操作系统漏洞信息，以及受支持和不受支持的操作系统的语言包漏洞信息。

Pub/Sub 通知

Artifact Registry 会将更改发布到与 Container Registry 相同的 gcr 主题。如果您已经在 Artifact Registry 所在的项目中将 Pub/Sub 与 Container Registry 搭配使用，则无需进行额外配置。

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

服务边界

借助 VPC Service Controls，您可以为 Google 代管式服务的资源配置安全边界，并控制跨边界的数据移动。

如需查看相关说明，请参阅在服务边界内保护代码库。

清理 Container Registry 映像

准备好停止使用 Container Registry 后，请通过删除 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. 如需确认删除，请输入存储桶名称，然后点击删除。

gsutil

如果您要批量删除存储桶中的十万张图片或更多图片，请避免使用 gsutil，因为删除过程需要很长时间才能完成。请改用 Google Cloud 控制台来执行此操作。

如需删除存储桶，请使用带有 -r 标志的 gsutil rm 命令。

gsutil rm -r gs://BUCKET-NAME

将 BUCKET-NAME 替换为 Container Registry 存储桶名称。在存储桶名称中，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 与这些服务搭配使用，也是如此。

后续步骤