本页面介绍如何使用 Docker 推送和拉取容器映像。如果您要排查 Google Kubernetes Engine 中的问题,还介绍了如何使用 crictl
工具拉取映像。
如需了解如何部署到 Google Cloud 运行时环境,请参阅部署到 Google Cloud。
如需了解如何列出、标记和删除映像,请参阅管理映像。
须知事项
所需的角色
如需获取推送和拉取映像所需的权限,请让管理员授予您代码库的以下 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。
标记本地映像
确保您已通过代码库进行身份验证。
确定映像的名称。完整映像名称的格式为:
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
如需详细了解映像名称格式(包括如何处理网域级项目),请参阅代码库和映像名称。
使用代码库名称标记本地映像。
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
确保您已通过代码库进行身份验证。
如果您使用
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-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 拉取映像
代码库模式:标准、远程、虚拟
确保您已通过代码库进行身份验证。
如果您使用
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 是存储映像的代码库的单区域或多区域位置,例如
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
- LOCATION 是存储映像的代码库的单区域或多区域位置,例如
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
映像注册表