推送和拉取映像

本页面介绍了如何使用 Docker 推送和拉取容器映像。它还 提供有关使用 crictl 工具拉取映像的信息 排查 Google Kubernetes Engine 中的问题。

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

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

准备工作

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

所需的角色

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

• 拉取映像： Artifact Registry Reader (roles/artifactregistry.reader)
• 标记和推送映像： Artifact Registry Writer (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-west1-docker.pkg.dev。

• gcloud CLI 凭据帮助程序：

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

• 独立凭据帮助程序

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

使用访问令牌

对于访问令牌身份验证，您可以生成一个令牌并将其用作密码 替换为 docker login 命令。令牌有效期为 60 分钟，因此您应在标记、推送或提取映像之前进行身份验证。

以下示例使用服务账号生成访问令牌 假冒，然后 进行身份验证您必须拥有 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-west1-docker.pkg.dev 进行身份验证。

Linux

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

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-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 是存储映像的代码库所在的单区域或多区域位置。

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

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

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

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

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

   本示例的此映像名称为：

   us-west1-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-west1-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-west1-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-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-west1-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 是 单区域或多区域 映像所在代码库的位置 。
   • PROJECT 是您的 Google Cloud 控制台 项目 ID。 如果您的项目 ID 包含英文冒号 (`:`)，请参阅网域级项目。
   • REPOSITORY 是存储了映像的代码库的名称。
   • IMAGE 是代码库中的映像名称。
   • TAG 是您要拉取的映像版本的标记。
   • IMAGE-DIGEST 是映像内容的 sha256 哈希值。图片的每个版本都有一个唯一的图片摘要。在 Google Cloud 控制台中 点击特定图片可查看其元数据此摘要将被列为映像摘要。

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

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

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

   docker pull us-west1-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 映像注册库