此页面由 Cloud Translation API 翻译。

推送和拉取映像

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

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

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

准备工作

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

所需的角色

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

拉取映像： Artifact Registry 读取者 (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 的密码命令。

例如，以下命令使用 base64 编码的服务账号密钥添加到 key.json 文件中，以便向 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

标记本地映像

确保您已通过代码库身份验证。
确定映像的名称。完整映像名称的格式为：
```
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
```
注意：将存储在仓库中的映像的名称可以与本地机器上的映像名称不同。

如需详细了解映像名称格式包括处理网域级项目、请参阅代码库和映像名称。
使用代码库名称标记本地映像。
```
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

确保您已通过代码库身份验证。

如果您使用的是 gcloud auth configure-docker 或使用 docker-credential-gcr configure-docker 配置 Docker 客户端。验证目标主机名是否包含在您的 Docker 配置文件中。
使用以下命令推送带有标记的映像：
```
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 拉取映像

仓库模式：标准、远程、虚拟

确保您已通过代码库身份验证。

如果您使用的是 gcloud auth configure-docker 或使用 docker-credential-gcr configure-docker 配置 Docker 客户端。验证目标主机名是否包含在您的 Docker 配置文件中。
如需从代码库中拉取映像，请使用以下命令：
```
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 中拉取映像，请执行以下操作：

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

转到“虚拟机实例”
通过 SSH 连接到需要排查的节点问题

获取用于向代码库进行身份验证的访问令牌。

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

使用 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 映像注册表

推送和拉取映像

准备工作

所需的角色

向代码库进行身份验证

使用凭据帮助程序

使用访问令牌

Linux

Windows

使用服务账号密钥

Linux

Windows

推送映像

标记本地映像

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

使用 Docker 拉取映像

使用 crictl 拉取映像

后续步骤

使用 `crictl` 拉取映像