推送和拉取映像

推送（上传）和拉取（下载）映像是最常见的 Container Registry 任务。本文档重点介绍如何使用 Docker 推送和拉取映像。

如果您使用的是 Cloud Build，请参阅 Cloud Build 文档，了解如何构建容器并将其推送到 Container Registry。

如需了解如何列出、标记和删除映像，请参阅管理映像。

准备工作

确保您已经：

  1. 在您的项目中启用 Container Registry。

  2. 安装和配置的 Docker。

添加注册表

您可以将以下 Container Registry 注册表添加到项目中：

主机名 存储位置
gcr.io 将映像存储在美国的数据中心
asia.gcr.io 将映像存储在亚洲的数据中心
eu.gcr.io 将映像存储在欧盟成员国内的数据中心
us.gcr.io 将映像存储在美国的数据中心

第一次将映像推送到主机时，需要在项目中创建注册表以及相应的 Cloud Storage 存储分区。此初始推送操作需要项目范围的权限来创建存储分区。

当项目中存在注册表主机后，您可以配置存储分区的权限，以控制对注册表中映像的访问权限。

要添加注册表并配置权限，请执行以下操作：

  1. 验证您是否拥有所需的权限。您必须具有 Storage Admin 角色 (roles/storage.admin) 或拥有相同权限的自定义角色或预定义角色。

    如需了解如何在项目级授予 Storage Admin 角色， 请参阅 IAM 文档。

  2. 将初始映像推送到主机。例如，以下命令：

    • 从 Docker Hub 中拉取 busybox 映像
    • 使用映像在 Container Registry 中的目标路径（包括 gcr.io 注册表主机和项目 ID my-project）标记该映像
    • 将映像推送到注册表
    docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox

Container Registry 会将注册表添加到项目中，为注册表创建存储分区并存储映像。

现在，您可以对注册表存储分区配置访问权限控制，以向其他用户授予注册表访问权限。

将映像推送到注册表

如需使用 Docker 或其他第三方工具将任何本地映像推送到 Container Registry，您首先需要使用注册表名称标记该映像，然后再进行推送。

以下因素可能会影响大型映像的上传：

上传时间
发送到 Container Registry 的任何请求都有 2 小时的超时限制。如果您使用访问令牌向 Container Registry 进行身份验证，令牌会在 60 分钟后过期。如果您预计上传时间超过 60 分钟，请使用其他身份验证方法。
映像大小
Container Registry 使用 Cloud Storage 作为每个注册表的底层存储系统。Cloud Storage 配额和限制适用于每个注册表，其中包括存储对象的大小不能超过 5 TB。
Container Registry 不支持 Docker 分块上传。某些工具支持通过分块上传或单一上传来上传大型映像。您必须使用单一上传将映像推送到 Container Registry。

所需权限

推送映像需要以下 Cloud Storage 角色之一或具有相同权限的角色：

将第一个映像推送到项目中的注册表

角色：Google Cloud 项目级的 Storage Admin (roles/storage.admin)。预定义的 Owner 角色包含这些权限。

您首次将映像推送到项目中的注册表主机（例如 gcr.io）时，Container Registry 会为注册表创建一个存储分区。Storage Admin 角色具有创建存储分区所需的权限。

将映像推送到项目中的现有注册表

角色：针对以下角色的 Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) 注册表存储桶。

此角色具有为项目中现有注册表主机推送和拉取映像的权限。例如，如果您的项目仅包含 gcr.io 注册表，则具有 Storage Legacy Bucket Writer 角色的用户可以将映像推送到 gcr.io，但不能将映像推送到 asia.gcr.io。

如需了解如何授予针对注册表的权限，请参阅配置访问权限控制。

使用注册表名称标记本地映像

要标记映像，请执行以下操作：

  1. 验证您已配置 Container Registry 身份验证。

  2. 确定 Container Registry 中映像的名称：

    1. 选择一个主机名，以指定映像的存储位置。

      • gcr.io 在美国的数据中心托管映像，但该位置未来可能会发生变化
      • us.gcr.io 在美国的数据中心托管映像，使用的存储分区与 gcr.io 托管的映像不同
      • eu.gcr.io 在欧盟托管映像
      • asia.gcr.io 在亚洲的数据中心托管映像

      这些位置对应于 Cloud Storage 存储分区的多区域位置。如果您将映像推送到使用新主机名的注册表，Container Registry 会在指定的多区域位置中创建一个存储分区。该存储分区是注册表的底层存储空间。在项目中，所有使用相同主机名的注册表都共用一个存储分区。

      在控制台中，映像的主机名将列在位置下。

    2. 选择一个目标映像名称，该名称可能与本地机器上的映像名称不同。例如，本地图片可能称为 web-image，但您希望以如下形式将其存储在 Container Registry 中： web-site

    3. 合并主机名、您的 Google Cloud 控制台 项目 ID、 和目标映像名称：

      HOSTNAME/PROJECT-ID/TARGET-IMAGE

      请思考以下示例：

      • 主机名：gcr.io
      • Google Cloud 项目：my-project
      • 目标映像名称：web-site

      将主机名、项目和目标映像名称组合在一起，即可获得用于标记的完整映像路径：

      gcr.io/my-project/web-site

      如果您的项目 ID 包含英文冒号 (:)，请参阅网域级项目。

  3. 使用上一步中的名称标记本地映像。如果要加标签 此版本的映像，请在其中添加标记名称。

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG

    替换以下内容：

    • SOURCE_IMAGE 是本地映像名称或映像 ID。
    • HOSTNAME 是您在第 2 步中选择的注册表主机。
    • PROJECT 是 Google Cloud 项目 ID。
    • TARGET-IMAGE 是映像存储于 Container Registry
    • TAG 是您要与此映像版本关联的标记。

    例如，此命令将本地映像 web-image 标记为 Container Registry 中的 gcr.io/my-project/web-site，带有 v1.5 标记

    docker tag web-image gcr.io/my-project/web-site:v1.5

    如果您未指定标记，Docker 会添加默认的 latest 标记。由于 latest 是默认标记，因此它表示最近用 latest 标记的映像版本，而非映像的最新版本。

Docker 会使用您在命令中指定的映像名称和标记为您的映像添加标记。

将带有标记的映像推送到 Container Registry

  1. 验证您已配置 Container Registry 身份验证。

  2. 将带标记的映像推送到 Container Registry：

    运行以下命令以推送带有特定标记的映像：

    docker push HOSTNAME/PROJECT-ID/IMAGE:TAG

    如果省略 :TAG，Docker 将推送该映像的版本 带有latest标记。

    例如，以下命令使用gcr.io/my-project/web-site （带有 v1.5 标记）：

    docker push gcr.io/my-project/web-site:v1.5

当您将映像推送到您的集群中尚不存在的注册表主机时， 项目时，Container Registry 会为注册表主机创建一个存储桶。

如需查看您推送的映像，请执行以下操作：

  • 前往 Google Cloud 控制台，查看 和映像

  • 运行 gcloud container images list-tags 来查看映像标记和自动生成的摘要：

    gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE

    此命令的输出类似如下所示：

    DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..

从注册表中拉取映像

拉取映像需要注册表存储桶的 Storage Object Viewer 角色，或者具有相同权限的角色。

要从 Container Registry 中拉取映像，请使用以下命令：

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

或

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

其中：

  • HOSTNAME 列在控制台的位置下方。可以是以下四个选项之一：gcr.io、us.gcr.io、eu.gcr.io 或 asia.gcr.io。
  • PROJECT-ID 是您的 Google Cloud 控制台 项目 ID。 如果您的项目 ID 包含英文冒号 (:)，请参阅网域级项目。
  • IMAGE 是 Container Registry 映像的名称。
  • TAG 是应用于映像的标记。在注册表中，每个映像的标记各不相同。
  • IMAGE_DIGEST 是映像内容的 sha256 哈希值。在 Google Cloud 控制台，点击 以查看其元数据。此摘要将被列为映像摘要。

要获取特定映像的拉取命令，请执行以下操作：

  1. 点击映像名称以转至特定注册表。

  2. 在该注册表中，选中要拉取的映像版本旁边的复选框。

  3. 点击页面顶部的显示拉取命令。

  4. 复制拉取命令，以此使用标记或摘要标识映像。

后续步骤