推送和拉取映像

推送(上传)和拉取(下载)映像是最常见的 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,但您希望将其作为 web-site 存储在 Container Registry 中

    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 是您要与此映像版本关联的标记。

    例如,以下命令在 Container Registry 中将本地映像 web-image 标记为 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 标记的映像版本。

    例如,以下命令会推送带有 v1.5 标记的映像 gcr.io/my-project/web-site

    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.ious.gcr.ioeu.gcr.ioasia.gcr.io
  • PROJECT-ID 是您的 Google Cloud 控制台项目 ID。如果您的项目 ID 包含英文冒号 (:),请参阅网域级项目
  • IMAGE 是 Container Registry 映像的名称。
  • TAG 是应用于映像的标记。在注册表中,每个映像的标记各不相同。
  • IMAGE_DIGEST 是映像内容的 sha256 哈希值。在 Google Cloud 控制台中,点击特定映像以查看其元数据。此摘要将被列为映像摘要

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

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

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

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

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

后续步骤