有关 Docker 的更改

本文档将向您介绍 Container Registry 和 Artifact Registry 在使用 Docker 进行容器映像身份验证、推送和拉取方面的区别。

在本指南中，我们将重点比较标准 Artifact Registry 仓库，即独立于 Container Registry 且支持所有 Artifact Registry 功能的常规 Artifact Registry 仓库。

如果您的管理员设置了支持 gcr.io 网域的代码库，系统会自动将对 gcr.io 主机名的请求重定向到相应的 Artifact Registry 代码库。使用托管在 上的 gcr.io 代码库 您必须有一个适当的 Artifact Registry 角色或符合以下条件的角色： 同等权限。

如需了解在使用 Cloud Build 构建并部署到 Cloud Run 或 Google Kubernetes Engine 时 Container Registry 和 Artifact Registry 之间的区别，请参阅 Cloud Build、Cloud Run 和 GKE 的变更。

您可以参考这些信息，调整以 Container Registry with Docker 为重点的现有命令、配置或文档。

准备工作

本文档假定您满足以下条件：

  1. 在您的项目中启用了 Artifact Registry。
  2. 已经安装 Docker。Docker 包含在 Cloud Shell 中。

概览

概括而言，将 Docker 与 Container Registry 或 Artifact Registry 搭配使用的工作流相同。

Container Registry Artifact Registry
管理员
  1. 启用 Container Registry API
  2. 通过推送初始配置文件，添加注册表主机，例如“gcr.io” 将映像发送到主机
  3. 为存储桶授予 Cloud Storage 角色，以便注册表主机可以访问映像。
 管理员
  1. 启用 Artifact Registry API
  2. 添加 Docker 代码库。
  3. 授予 Artifact Registry 角色以提供对映像的访问权限。
注册表用户
  1. 将图片定义为 Dockerfile 文件。
  2. 构建映像。
  3. 向注册库进行身份验证。
  4. 标记映像并将其推送到注册表。
  5. 从注册表中拉取映像，或将其部署到 Google Cloud 运行时。
 注册表用户
  1. 将图片定义为 Dockerfile 文件。
  2. 构建映像。
  3. 向注册库进行身份验证。
  4. 标记映像并将其推送到注册表。
  5. 从注册表中拉取映像，或将其部署到 Google Cloud 运行时。

但是，Container Registry 的一个快捷方式是 和用户角色整合到一个工作流程中。此快捷键常见于：

  • 快速入门和教程 都没有广泛权限
  • 使用 Cloud Build 的工作流，因为 Cloud Build 服务账号有权在同一 Google Cloud 项目中添加注册表主机。

快捷方式工作流如下所示：

  1. 启用 Container Registry API
  2. 向将访问 Container Registry 的账号授予权限。

  3. 向注册库进行身份验证。最简单的身份验证选项是使用 Google Cloud CLI 中的 Docker 凭据帮助程序。这是一次性配置步骤。

    gcloud auth configure-docker

  4. 构建并标记映像。例如，以下命令会构建并标记映像 gcr.io/my-project/my-image:tag1：

    docker build -t gcr.io/my-project/my-image:tag1

  5. 将映像推送到注册表。例如：

    docker push gcr.io/my-project/my-image:tag1

    如果项目中不存在 gcr.io 注册表主机，Container Registry 会先添加主机，然后再上传映像。

  6. 从注册表中拉取映像或将其部署到 Google Cloud 运行时。例如：

    docker pull gcr.io/my-project/my-image:tag1

此工作流依赖于以下快捷键：

  • 推送映像的账号具有 Storage Admin 角色或具有相同权限的角色（例如 Owner）。此角色的广泛权限允许对项目中的所有存储桶（包括 Container Registry 未使用的存储桶）进行读取和写入访问。
  • 当您启用某些 Google Cloud API 时，系统会自动启用 Container Registry API。这意味着 服务对同一项目中的 Container Registry 具有隐式访问权限。对于 例如，可以在 Cloud Build 中运行构建作业的用户可以 和添加注册表主机。

在 Artifact Registry 中，管理员和 可以更改构建和部署工作流中步骤的仓库用户角色。 如需将 Container Registry 工作流调整为适用于 Artifact Registry，请进行以下更改。每个步骤都链接到有关修改工作流的更多信息。

  1. 新功能：启用 Artifact Registry API。

    您必须启用 Artifact Registry API。Cloud Build 和运行时环境（例如 Cloud Run 和 GKE）不会自动为您启用该 API。

  2. New：创建目标 Docker 代码库（如果没有的话） 已存在。您必须先创建一个仓库，然后才能向其推送映像。推送映像不会触发系统创建仓库，而且 Cloud Build 服务账号也没有创建仓库的权限。

  3. 向将与 Artifact Registry 交互的账号授予权限。

  4. 已更改：对代码库进行身份验证。如果您在 gcloud CLI 中使用凭据帮助程序，则必须指定要添加到 Docker 客户端配置中的主机。对于 例如，以下命令会添加主机 us-central1-docker.pkg.dev：

    gcloud auth configure-docker us-central1-docker.pkg.dev

  5. 已更改：构建并标记图片。

    以下示例命令与 Container Registry 示例相同，但使用的是映像的 Artifact Registry 代码库路径。

    docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  6. 已更改：使用 Artifact Registry 路径将映像推送到代码库。例如：

    docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  7. 已更改：使用 Artifact Registry 路径。例如：

    docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

启用 API

要点：

以下对比介绍了如何为每项服务启用该 API：

Container Registry

您必须启用 Container Registry API 将 Docker 或其他第三方客户端与 Container Registry 搭配使用之前。

启用以下 Google Cloud API 后，Container Registry API 也会自动启用：

  • App Engine 柔性环境
  • Cloud Build
  • Cloud Run 函数
  • Cloud Run
  • Artifact Analysis 中的容器扫描或按需扫描
  • Google Kubernetes Engine

默认情况下，如果用户可以在 Cloud Build 中运行 build、使用 Artifact Analysis 扫描容器或将容器部署到 Google Cloud 运行时，则当 Container Registry 位于同一项目中时，他们会隐式拥有对 Container Registry 中映像的访问权限。

Artifact Registry

您必须启用 Artifact Registry API 然后才能将 Docker 客户端或其他 Google Cloud 服务与 Artifact Registry

例如 Cloud Build、Cloud Run GKE 不会自动启用 Artifact Registry API。

您可以使用 gcloud 在同一项目中启用多个 API。例如，要启用 Cloud Build API 和 Artifact Registry API，请运行以下命令：

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

添加注册表和代码库

要点：

  • 您必须先创建 Artifact Registry Docker 代码库，然后才能将映像推送到该代码库。

    注册数据库创建步骤通常不包含在 介绍了如何将映像推送到 Container Registry 管理员权限可将注册表添加到项目，并将初始推送至 注册表主机。

  • Container Registry 会将所有映像存储在同一多区域位置的同一存储桶中。在 Artifact Registry 中，您可以创建多个 位于同一区域或多区域的存储库。

以下比较介绍了每项服务中的代码库设置：

Container Registry

在 Container Registry 中，您最多可向项目添加四个注册表主机。 您可以通过推送第一个映像来添加注册表主机。

  1. 要将 gcr.io 等注册表添加到您的项目，请使用 项目级别的 Storage Admin 角色推送初始映像。

    例如，如果项目中不存在 gcr.io 主机 my-project，推送映像 gcr.io/my-project/my-image:1.0 触发器 执行下列步骤：

    1. 将 gcr.io 主机添加到项目中
    2. 在项目中为 gcr.io 创建一个存储桶。
    3. 将图片存储为 gcr.io/my-project/my-image:1.0

  2. 完成此初始推送后，您可以为其他用户授予对存储桶的权限。

在项目中，注册表主机将所有映像存储在同一存储空间中 存储桶。在以下示例中，项目 my-project 有两个名为 注册表 gcr.io 中的 web-app。一个位于项目 ID 下 my-project。另一个映像位于代码库 team1 中。

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

具有 Artifact Registry 代码库管理员角色的账号必须先创建代码库，然后您才能将映像推送到该代码库。然后，您可以为其他用户授予对代码库的权限。

在 Artifact Registry 中，每个代码库都是独立的资源。因此，所有映像路径都必须包含代码库。

有效的映像路径：

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

映像路径无效（不包含仓库）：

us-central1-docker.pkg.dev/my-project/web-app:1.0

以下示例展示了将映像推送到缺失的仓库时会失败的情况。

  • 如果 us-central1-docker.pkg.dev/my-project/team1 不存在，则将映像推送到 us-central1-docker.pkg.dev/my-project/team1。
  • 在以下情况下将映像推送到 us-central1-docker.pkg.dev/my-project/team2： “us-central1-docker.pkg.dev/my-project/team1”存在，但 “us-central1-docker.pkg.dev/my-project/team2”不存在。

授予权限

要点：

  • 向要登录的账号授予适当的 Artifact Registry 角色 与 Artifact Registry 搭配使用
  • Google Cloud 服务对二者都拥有等效的读取或写入权限 Container Registry 和 Artifact Registry不过，默认的 Cloud Build 服务账号无法创建代码库。
  • Container Registry 支持存储桶级别的访问权限控制。 Artifact Registry 支持仓库级访问权限控制。

以下对比介绍了每项服务中的权限设置：

Container Registry

Container Registry 使用 Cloud Storage 角色来控制访问权限。

存储桶级别的 Storage Object Viewer
从项目中的现有注册表主机拉取（读取）映像。
存储桶级别的 Storage 旧版存储桶写入者
为项目中的现有注册表主机推送（写入）和拉取（读取）映像。
项目级 Storage Admin
将初始映像推送到主机，以向项目添加注册表主机。

在初始映像推送到注册表后，您可以向需要访问存储桶的其他账号授予 Cloud Storage 角色。请注意， 拥有 Storage Admin 角色中所有权限的账号都可以读取、写入和 删除整个项目中的存储分区和存储对象。

存储桶的权限会应用于注册表中的所有代码库。例如，对 Cloud Storage 存储分区拥有 Storage Object Viewer 权限的用户 gcr.io/my-project 的存储桶可以读取以下所有代码库中的图片：

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry 有自己的角色来控制访问权限。这些角色可在管理员角色和代码库用户角色之间进行明确分离。

只有管理代码库的账号才具有 Artifact Registry “Repository Administrator”或“Artifact Registry Administrator”角色。

Artifact Registry Reader
列出工件和代码库。下载工件。
Artifact Registry Writer
列出工件和代码库。下载制品，上传新制品 以及添加或更新代码。
Artifact Registry Repository Administrator
Artifact Registry Writer 权限和删除权限 工件和标记。
Artifact Registry Administrator
Artifact Registry Repository Administrator 权限 可以创建、更新、删除代码库以及授予代码库的权限。

您可以在代码库级别应用这些权限。例如：

  • 向 Team 1 授予对 us-central1-docker.pkg.dev/my-project/team1 的访问权限
  • 向“us-central1-docker.pkg.dev/my-project/team2”的团队 2 授予访问权限。

如需详细了解如何授予 Artifact Registry 权限，请参阅 访问权限控制文档。

向注册表进行身份验证

要点：

  • Artifact Registry 支持与 Container Registry 使用相同的身份验证方法。
  • 对于 Docker 凭据帮助程序，您必须指定要添加到 Docker 的主机 客户端配置。
  • 如需使用 docker login 进行身份验证，请使用 Artifact Registry 主机 而不是 Container Registry 主机

使用凭据帮助程序

默认情况下，命令 gcloud auth configure-docker 和独立凭据帮助程序仅针对 *.gcr.io 主机名配置 Docker。对于 Artifact Registry 您必须指定要添加到 Docker 客户端的 Artifact Registry 主机列表 配置。

例如，要针对该区域中的 Docker 代码库设置身份验证，请执行以下操作： us-central1，请运行以下命令：

gcloud auth configure-docker us-central1-docker.pkg.dev

如果您稍后在 us-east1 和 asia-east1 中添加代码库，则必须运行以下命令： 将相应的区域级主机名添加到您的 Docker 配置。

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

如需详细了解 Artifact Registry 身份验证方法，请参阅 为 Docker 设置身份验证。

使用密码身份验证

登录 Docker 时，请使用 Artifact Registry 主机名，而不是 *.gcr.io 主机名。以下示例展示了使用 以 base64 编码的服务账号密钥复制到主机 us-central1-docker.pkg.dev：

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

构建和标记映像

要点： - Artifact Registry 为代码库使用不同的主机名。

标记映像时，请使用 Artifact Registry 路径，而不是 Container Registry 路径。例如：

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

将映像推送到注册表

要点： - 在 Artifact Registry 中，目标代码库必须已存在，然后才能推送 图片。 - Artifact Registry 对代码库使用不同的主机名。

推送映像时，请使用 Artifact Registry 路径，而不是 Container Registry 路径。例如：

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

从注册表中拉取映像

要点：

  • Artifact Registry 主机名不同于 Container Registry 主机名。

拉取映像时，请使用 Artifact Registry 路径，而不是 Container Registry 路径。例如：

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

如需了解将映像部署到 Google Cloud 运行时（例如 Cloud Run 和 GKE）的示例，请参阅部署映像。