改用标准代码库

如果您使用 Container Registry 来管理容器映像，那么此页面将介绍如何设置 pkg.dev 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 的价格。

所需的角色

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

  • 如需创建 Artifact Registry 制品库并授予对各个制品库的访问权限，请使用以下角色： Artifact Registry Administrator (roles/artifactregistry.admin)
  • 如需查看和管理应用于 Cloud Storage 存储分区的现有 Container Registry 配置，请执行以下操作： 存储空间管理员 (roles/storage.admin)
  • 如需在项目一级授予代码库访问权限：Project IAM Admin (roles/resourcemanager.projectIamAdmin) 或具有等效权限的角色，例如 Folder Admin (roles/resourcemanager.folderAdmin) 或 Organization Admin (roles/resourcemanager.organizationAdmin)

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

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

概览

pkg.dev 制品库是支持所有功能的常规 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 Reader
(roles/artifactregistry.reader) 		Artifact Registry 仓库或 Google Cloud 项目
推送和拉取映像（读取和写入） Storage Legacy Bucket Writer
(roles/storage.legacyBucketWriter)		 Artifact Registry Writer
(roles/artifactregistry.writer)		 Artifact Registry 仓库或 Google Cloud 项目
推送、拉取和删除映像 Storage Legacy Bucket Writer
(roles/storage.legacyBucketWriter)		 Artifact Registry Repository Administrator
(roles/artifactregistry.repoAdmin)		 Artifact Registry 仓库或 Google Cloud 项目
创建、管理和删除代码库 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 角色，请参阅配置角色和权限。

向代码库进行身份验证

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 后，这两个产品都会启用 Artifact Analysis 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 命令 gcloud artifacts 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. 如需确认删除，请输入存储分区名称，然后点击删除。

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 搭配使用也是如此。

后续步骤