推送和拉取映像

本页面介绍如何使用 Docker 推送和拉取容器映像。如果您要排查 Google Kubernetes Engine 中的问题，还介绍了如何使用 crictl 工具拉取映像。

如需了解如何部署到 Google Cloud 运行时环境，请参阅部署到 Google Cloud。

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

须知事项

1. 如果目标代码库不存在，请创建新代码库。
2. 您必须至少具有代码库的 Artifact Registry Writer 访问权限。
3. 安装 Docker（如果尚未安装）。

所需的角色

如需获取推送和拉取映像所需的权限，请让管理员授予您代码库的以下 IAM 角色：

• 拉取映像： Artifact Registry Reader (roles/artifactregistry.reader)
• 标记和推送映像： Artifact Registry 写入者 (roles/artifactregistry.writer)

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

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

向代码库进行身份验证

每当您将 Docker 或其他第三方客户端与 Docker 代码库一起使用时，都必须向代码库进行身份验证。本部分简要总结了成功进行身份验证所需满足的要求。如需了解详细说明，请参阅为 Docker 设置身份验证。

使用凭据帮助程序

如需 gcloud CLI 凭据帮助程序或独立凭据帮助程序，您使用的 Artifact Registry 主机必须位于 Docker 配置文件中。

Artifact Registry 不会自动将所有注册表主机添加到 Docker 配置文件。如果存在大量已配置的注册表，则 Docker 的响应速度会明显变慢。如需尽量减少配置文件中的注册表数量，请将所需的主机添加到该文件中。

如需确认配置了哪些主机，请运行以下命令，以显示配置文件的内容：

• Linux：cat ~/.docker/config.json
• Windows：cat %USERPROFILE%\.docker\config.json

credHelpers 部分列出了已配置的 Artifact Registry Docker 主机。 主机名以 -docker.pkg.dev 结尾。以下示例显示了为 gcloud CLI 凭据帮助程序配置的一些主机。

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

如果列表中没有您要使用的主机，请再次运行凭据帮助程序以添加该主机。例如，以下命令会添加 us-east1-docker.pkg.dev。

• gcloud CLI 凭据帮助程序：

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

• 独立凭据帮助程序

  docker-credential-gcr configure-docker us-east1-docker.pkg.dev
  

使用访问令牌

对于访问令牌身份验证，您可以生成令牌并通过 docker login 命令将其用作密码。令牌的有效期为 60 分钟，因此您应该在标记、推送或拉取映像前不久进行身份验证。

以下示例使用服务帐号模拟生成访问令牌，然后向 Artifact Registry 进行身份验证。您必须拥有 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator) 才能以这种方式生成令牌。

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

Windows

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

如果您无权模拟服务帐号，可以在 gcloud CLI 会话中激活服务帐号，然后获取令牌。 如需了解详情，请参阅有关设置访问令牌身份验证的说明。

使用服务帐号密钥

对于服务帐号密钥，您可以通过 docker login 命令将该密钥用作密码。

例如，以下命令使用 key.json 文件中采用 base64 编码的服务帐号密钥向 us-east1-docker.pkg.dev 进行身份验证。

Linux

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

Windows

docker login -u _json_key_base64 --password-stdin https://us-east1-docker.pkg.dev < key.json

如需了解详情，请参阅有关设置服务帐号密钥身份验证的说明。

推送映像

代码库模式：标准

如需将本地映像推送到标准 Docker 代码库，您可以使用代码库名称对其进行标记，然后推送该映像。

如果您的 Artifact Registry Docker 代码库已启用标记不可变性，则标记必须始终引用代码库中相同的映像摘要。在您推送到代码库的同一映像的其他版本上，不能使用该标记。如需详细了解映像摘要、标记和标记不可变性，请参阅容器映像版本。

大图片存在以下限制：

上传时间

如果您使用访问令牌向 Artifact Registry 进行身份验证，则令牌的有效期只有 60 分钟。如果您预计上传时间超过 60 分钟，请使用其他身份验证方法。

映像大小

工件大小上限为 5 TB。

Artifact Registry 不支持 Docker 分块上传。 某些工具支持通过分块上传或单次单体式上传来上传大图片。您必须使用单体式上传将映像推送到 Artifact Registry。

标记本地映像

1. 确保您已通过代码库进行身份验证。

2. 确定映像的名称。完整映像名称的格式为：

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   替换以下值：

   • LOCATION 是存储映像的代码库的单区域或多区域位置，例如 us-east1 或 us。

   • PROJECT-ID 是您的 Google Cloud 控制台项目 ID。如果您的项目 ID 包含英文冒号 (:)，请参阅网域级项目。

   • REPOSITORY 是存储了映像的代码库的名称。

   • IMAGE 是映像的名称。该名称可能与映像的本地名称不同。

   例如，假设一个映像具有以下特征：

   • 代码库位置：us-east1
   • 代码库名称：my-repo
   • 项目 ID：my-project
   • 本地映像名称：my-image
   • 目标映像名称：test-image

   本示例的此映像名称为：

   us-east1-docker.pkg.dev/my-project/my-repo/test-image
   

   注意：您将存储在代码库中的映像名称可能与本地机器上的映像名称不同。

   如需详细了解映像名称格式（包括如何处理网域级项目），请参阅代码库和映像名称。

3. 使用代码库名称标记本地映像。

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   将 SOURCE-IMAGE 替换为本地映像名称或映像 ID，并将 TAG 替换为相应标记。如果未指定标记，Docker 将应用默认的 latest 标记。

   如果启用了不可变映像标记设置（预览版），每个映像版本的标记（包括 latest 标记）必须是唯一的。如果一个映像已被代码库中同一映像的其他版本使用，您就无法将该映像推送到该代码库。如需验证代码库是否已启用此设置，请运行以下命令：

   gcloud artifacts repositories describe REPOSITORY \
       --project=PROJECT-ID \
       --location=LOCATION
   

   对于上一步中的示例映像，如果本地映像 my-image 位于当前目录中，请使用以下命令：

   docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image
   

   如果要应用特定标记，请使用以下命令：

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   如需使用示例映像标记 staging，请在命令中添加 :staging：

   docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

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

注意：Artifact Registry 不支持 Docker 分块上传。某些容器映像工具支持通过分块上传或单一上传来上传大型容器映像。将容器映像推送到 Artifact Registry 时，您必须使用单一上传。

1. 确保您已通过代码库进行身份验证。

   如果您使用 gcloud auth configure-docker 或 docker-credential-gcr configure-docker 配置 Docker 客户端，请验证目标主机名是否在 Docker 配置文件中。

2. 使用以下命令推送带有标记的映像：

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   此命令将推送带有 latest 标记的映像。如果要推送带有不同标记的映像，请使用以下命令：

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

当您推送映像时，它会存储在指定的代码库中。

推送您的映像后，您可以执行以下操作：

• 转到 Google Cloud 控制台以查看映像。

• 运行 gcloud 命令来查看映像的标记和自动生成的摘要：

  gcloud artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

  以下示例输出显示了被截断的映像摘要，但该命令始终返回完整的映像摘要。

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  

使用 Docker 拉取映像

代码库模式：标准、远程、虚拟

1. 确保您已通过代码库进行身份验证。

   如果您使用 gcloud auth configure-docker 或 docker-credential-gcr configure-docker 配置 Docker 客户端，请验证目标主机名是否在 Docker 配置文件中。

2. 如需从代码库中拉取映像，请使用以下命令：

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   或

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
   

   替换以下值：

   • LOCATION 是存储映像的代码库的单区域或多区域位置，例如 us-east1 或 us。
   • PROJECT 是您的 Google Cloud 控制台项目 ID。如果您的项目 ID 包含英文冒号 (:)，请参阅网域级项目。
   • REPOSITORY 是存储了映像的代码库的名称。
   • IMAGE 是代码库中的映像名称。
   • TAG 是您要拉取的映像版本的标记。
   • IMAGE-DIGEST 是映像内容的 sha256 哈希值。 映像的每个版本都有唯一的映像摘要。在 Google Cloud 控制台中，点击特定映像以查看其元数据。此摘要将被列为映像摘要。

   例如，假设一个映像具有以下特征：

   • 代码库位置：us-east1
   • 代码库名称：my-repo
   • 项目 ID：my-project
   • 映像名称：test-image
   • 标记：staging

   用于拉取映像的命令如下：

   docker pull us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Docker 会下载指定的映像。

如果您从远程代码库请求映像，远程代码库将从上游来源下载并缓存该映像（如果不存在缓存副本）。

如果您从虚拟代码库请求映像，Artifact Registry 会在上游代码库中搜索请求的映像。如果您请求在多个上游代码库中可用的版本，Artifact Registry 会根据为虚拟代码库配置的优先级设置选择要使用的上游代码库。

例如，假设某个虚拟代码库为上游代码库具有以下优先级设置：

• main-repo：优先级设置为 100
• secondary-repo1：优先级已设为 80。
• secondary-repo2：优先级已设为 80。
• test-repo：优先级已设为 20。

main-repo 具有最高优先级值，因此虚拟代码库始终首先搜索它。

secondary-repo1 和 secondary-repo2 的优先级均设置为 80。如果请求的映像在 main-repo 中不可用，Artifact Registry 接下来会搜索这些代码库。由于它们具有相同的优先级值，因此 Artifact Registry 可以选择从任一代码库提供映像（如果这两个代码库都提供了相应版本）。

test-repo 具有最低优先级值，如果其他上游仓库都没有存储的工件，则系统将提供该工件。

使用 crictl 拉取映像

crictl 是一个实用的命令行工具，可供 CRI 运行时开发者调试其运行时，而无需设置 Kubernetes 组件。如果您的 Google Kubernetes Engine 节点使用 containerd 运行时，您可以使用 crictl 从 Artifact Registry 中拉取映像。

由于 crictl 主要是一种问题排查工具，因此某些 docker 命令（例如推送或标记映像）不可用。

如需从 Artifact Registry 中拉取映像，请执行以下操作：

1. 在 Google Cloud 控制台中，转到虚拟机实例页面。

   转到“虚拟机实例”

2. 通过 SSH 连接到要进行问题排查的节点。

3. 获取用于代码库身份验证的访问令牌。

   curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

4. 使用 crictl pull --creds 和 access_token 值拉取映像

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

   或

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

   输出如下所示：

   Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

后续步骤

• 了解如何管理标记和删除映像。
• 如果要在 Compute Engine 上运行容器，请了解 Compute Engine 上的容器。
• 使用 crictl 调试 Kubernetes 节点
• 了解如何使用 crictl 从私有 Artifact Registry 代码库中拉取映像
• 详细了解如何配置 crictl 映像注册表