身份验证方法

本页面介绍如何配置第三方客户端以通过 Container Registry 进行身份验证。

与 Container Registry 集成的 Google Cloud 服务已预先配置了可以访问同一项目中代码库的权限。您无需为这些服务配置身份验证，但需验证权限是否已正确配置。

准备工作

  1. 验证您已启用 Container Registry API 并安装 gcloud CLI。如需相关说明，请参阅启用和停用服务。

  2. 验证用于身份验证的账号是否具有访问 Container Registry 的权限。我们建议您使用服务账号，而不是用户账号。

  3. 安装 Docker（如果尚未安装）。Cloud Shell 中包含 Docker。

  4. Docker 需要特别访问权限才能与注册表进行交互。 在 Linux 或 Windows 上，将您用于运行 Docker 命令的用户添加到 Docker 安全群组。在 MacOS 上，Docker Desktop 以 root 用户身份在虚拟机上运行，因此无需执行此步骤。

    Linux

    Docker 安全群组称为 docker。 如需添加用户名，请运行以下命令：

    sudo usermod -a -G docker ${USER}

    Windows

    Docker 安全群组称为 docker-users。 如需从管理员命令提示符添加用户，请运行以下命令：

    net localgroup docker-users DOMAIN\USERNAME /add

    其中

    • DOMAIN 是您的 Windows 网域。
    • USERNAME 是您的用户名。

    退出并重新登录以使群组成员资格变更生效。如果您使用的是虚拟机，则可能需要重启虚拟机才能使成员资格变更生效。

身份验证方法

您必须配置任何需要访问 Container Registry 的第三方客户端。

您可以使用以下身份验证方法：

gcloud 凭据帮助程序（推荐）
配置 Container Registry 凭据，以便直接在 gcloud 中配合 Docker 使用。请尽可能使用此方法，以便在短时间内安全访问您的项目资源。 此选项仅支持 Docker 版本 18.03 或更高版本。
独立凭据帮助程序
此选项主要用于配置凭据，以便在没有 Google Cloud CLI 时配合 Docker 使用。此选项仅支持 Docker 版本 18.03 或更高版本。
访问令牌
应用默认凭据提供服务账号用于访问 Google Cloud 资源的短期访问令牌。 使用 gcloud 作为凭证帮助程序是最安全的选择。
JSON 密钥文件

用户管理的密钥对，您可以将其用作服务账号的凭据。由于它是长期凭据，因此它是所有可用身份验证方法中最不安全的选项。

请尽可能使用访问令牌或其他可用的身份验证方法，以降低未经授权而访问工件的风险。 如果服务账号密钥未正确管理，则会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性以及管理服务账号密钥的最佳实践中所述的其他操作。如果系统阻止您创建服务账号密钥，您的组织可能会停用服务账号密钥创建功能。如需了解详情，请参阅管理默认安全的组织资源。

某些工具或工作流无法很好地支持使用 gcloud 作为凭据帮助程序。如果使用替代选项之一，请务必了解安全隐含的含义。

Docker 配置文件中的身份验证设置

Docker 将身份验证设置保存在配置文件 config.json 中。

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

文件中的不同身份验证方法分别对应不同的部分：

credHelpers
如果您使用 Docker 凭据帮助程序进行身份验证，Container Registry 将凭据帮助程序设置存储在文件的 credHelpers 部分中。
auths
如果您使用 Docker 以令牌或服务账号密钥作为密码进行登录，Docker 会将凭据存储在文件的 auths 部分。
credStore
如果您配置了凭据存储来管理凭据，则凭据存储的设置位于文件的 credStore 部分。

当 Docker 连接到注册表时，它首先会检查与主机关联的凭据帮助程序。因此，如果您的 config.json 在 credHelpers 和 auths 部分中均包含 Container Registry 设置，则 auths 部分中的设置会被忽略。

gcloud 凭据帮助程序

我们强烈建议您尽量使用这种方法。这样可确保在短时间内安全访问您的项目资源。

使用 gcloud CLI 在 Cloud Shell 或安装了 Google Cloud CLI 的任何环境中配置身份验证。Cloud Shell 包含最新版本的 Docker。

如需配置身份验证，请执行以下操作：

  1. 以将运行 Docker 命令的用户身份登录 gcloud。

    • 如需使用用户凭据配置身份验证，请运行以下命令：

      gcloud auth login

    • 如需使用服务账号凭据配置身份验证，请运行以下命令：

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

      其中

      • ACCOUNT 是格式为 [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 的服务账号名称。您可以在 Google Cloud 控制台的服务账号页面上查看现有服务账号，也可以使用命令 gcloud iam service-accounts list 查看
      • KEY-FILE 是服务账号密钥文件。如需了解如何创建密钥，请参阅 Identity and Access Management (IAM) 文档。

  2. 使用以下命令配置 Docker：

    gcloud auth configure-docker

    凭据会保存在用户的主目录中。

    • Linux：$HOME/.docker/config.json
    • Windows：%USERPROFILE%/.docker/config.json

独立凭据帮助程序

独立 Docker 凭据帮助程序将 Docker 配置为在 gcloud CLI 不可用的系统上向 Container Registry 进行身份验证。

该凭据帮助程序会自动或从其 --token-source 标志指定的位置提取 Container Registry 凭据，然后将凭据写入 Docker 的配置文件。这样，您就可以使用 Docker 的命令行工具 docker 直接与 Container Registry 进行交互。

如需配置身份验证，请执行以下操作：

  1. 以将运行 Docker 命令的用户身份登录机器。

  2. 从 GitHub 版本中下载 docker-credential-gcr：

    您可以选择使用 curl 命令行实用程序。例如：

    VERSION=2.1.23
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz docker-credential-gcr \
&& chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/

  3. 使用以下命令配置 Docker：

    docker-credential-gcr configure-docker

    凭据会保存在用户的主目录中。

    • Linux：$HOME/.docker/config.json
    • Windows：%USERPROFILE%/.docker/config.json

如需了解详情，请参阅 GitHub 上的独立 Docker 凭据帮助程序文档。

Docker 现已配置为向 Container Registry 进行身份验证。如需推送和拉取映像，请确保正确配置权限。

访问令牌

您可以生成短期 OAuth 访问令牌以向 Container Registry 进行身份验证。由于令牌在 60 分钟内有效，因此请在使用它连接 Container Registry 之前一个小时内申请。

  1. 创建将与 Container Registry 交互的新服务账号。

    控制台

    1. 在 Google Cloud 控制台中，转到创建服务账号页面。

      转到“创建服务账号”页面

    2. 选择要使用的项目。

    3. 在服务账号名称字段中，输入一个名称。

    4. 可选：在服务账号说明字段中，输入说明。

    5. 点击创建。

    6. 点击选择角色字段。在所有角色下，根据您要授予服务账号的权限，选择合适的 Cloud Storage 角色。

    7. 点击完成。

    gcloud

    您可以使用本地机器上的 Google Cloud CLI 或在 Cloud Shell 中运行以下命令。

    1. 创建服务账号。将 NAME 替换为服务账号的名称。

      gcloud iam service-accounts create NAME

    2. 向服务账号授予角色。将 PROJECT_ID 替换为您的项目 ID，将 ROLE 替换为服务账号的相应 Cloud Storage 角色。此角色适用于项目中的所有代码库。 您可以稍后更改该角色，还可以向特定代码库上的服务账号授予不同的角色。

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

  2. 获取将与 Container Registry 交互的服务账号的密钥。

    控制台

    1. 在 Google Cloud 控制台中，转到服务账号页面。

      转到“服务账号”页面

    2. 点击您要使用的服务账号的电子邮件地址。

    3. 点击密钥。

    4. 依次点击添加密钥和创建新密钥。

    5. 点击创建。包含密钥的 JSON 文件随即会下载到您的计算机中。

      此页面上的说明使用此密钥文件的文件名 keyfile.json。

    6. 点击关闭。

    gcloud

    您可以使用本地机器上的 Google Cloud CLI 或在 Cloud Shell 中运行以下命令。

    此页面上的说明使用密钥文件的文件名 keyfile.json。

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

  3. 运行以下命令，以服务账号身份登录 Google Cloud CLI。

    gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

    其中

    • ACCOUNT 是格式为 [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 的服务账号名称。
    • KEY-FILE 是服务账号密钥文件。如需了解如何创建密钥，请参阅 IAM 文档。

  4. 验证是否为服务账号正确配置了权限。如果您使用的是 Compute Engine 服务账号，则必须正确配置权限和访问权限范围。

  5. 获取服务账号的访问令牌。由于令牌只在短时间内有效，因此请在使用它连接 Container Registry 之前一个小时内申请。

    运行以下命令：

    Linux

    gcloud auth print-access-token | docker login -u oauth2accesstoken \
    --password-stdin https://HOSTNAME

    Windows

    gcloud auth print-access-token |
    docker login -u oauth2accesstoken --password-stdin https://HOSTNAME

    其中 HOSTNAME 为 gcr.io、us.gcr.io、eu.gcr.io 或 asia.gcr.io。

Docker 现已通过 Container Registry 身份验证。

JSON 密钥文件

服务账号密钥是长期有效的密钥对，您可以将其用作服务账号的凭据。与 OAuth 访问令牌不同，服务账号密钥不会过期。

任何有权访问服务账号的有效私钥的人员都可以通过该服务账号访问资源。由 Google Cloud 自动创建的某些服务账号（例如 Container Registry 服务账号）会被授予父级项目的 Editor 角色（具有读写权限）。Compute Engine 默认服务账号配置为对同一项目中的存储空间具有只读权限。

此外，密钥访问服务账号（以及服务账号可访问的数据）的生命周期与已下载密钥的用户的生命周期无关。

请遵循以下准则来限制对容器映像的访问：

  • 创建仅用于与 Container Registry 交互的专用服务账号。
  • 为特定角色授予服务账号所需的最低访问权限。
  • 按照管理凭据的最佳做法操作。

要创建仅用于 Container Registry 代码库的新服务账号和服务账号密钥，请执行以下操作：

  1. 创建将与 Container Registry 交互的新服务账号。

    控制台

    1. 在 Google Cloud 控制台中，转到创建服务账号页面。

      转到“创建服务账号”页面

    2. 选择要使用的项目。

    3. 在服务账号名称字段中，输入一个名称。

    4. 可选：在服务账号说明字段中，输入说明。

    5. 点击创建。

    6. 点击选择角色字段。在所有角色下，为服务账号选择合适的 Cloud Storage 角色。

    7. 点击完成。

    gcloud

    您可以使用本地机器上的 Google Cloud CLI 或在 Cloud Shell 中运行以下命令。

    1. 创建服务账号。将 NAME 替换为服务账号的名称。

      gcloud iam service-accounts create NAME

    2. 向服务账号授予角色。将 PROJECT_ID 替换为您的项目 ID，将 ROLE 替换为服务账号的相应 Cloud Storage 角色。

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

  2. 获取将与 Container Registry 交互的服务账号的密钥。

    控制台

    1. 在 Google Cloud 控制台中，转到服务账号页面。

      转到“服务账号”页面

    2. 点击您要使用的服务账号的电子邮件地址。

    3. 点击密钥。

    4. 依次点击添加密钥和创建新密钥。

    5. 点击创建。包含密钥的 JSON 文件随即会下载到您的计算机中。

      此页面上的说明使用此密钥文件的文件名 keyfile.json。

    6. 点击关闭。

    gcloud

    您可以使用本地机器上的 Google Cloud CLI 或在 Cloud Shell 中运行以下命令。

    此页面上的说明使用密钥文件的文件名 keyfile.json。

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

  3. 验证是否为服务账号正确配置了权限。如果您使用的是 Compute Engine 服务账号，则必须正确配置权限和访问权限范围。

  4. 使用服务账号密钥作为密码向 Docker 进行身份验证。

    Linux/macOS

    cat KEY-FILE | docker login -u _json_key --password-stdin \
https://HOSTNAME

    Windows

    Get-Content KEY-FILE |
docker login -u _json_key --password-stdin https://HOSTNAME

    替换以下内容：

    • KEY-FILE 是 JSON 格式的服务账号密钥文件的名称。
    • HOSTNAME 是 gcr.io、us.gcr.io、eu.gcr.io 或 asia.gcr.io。

Docker 现已通过 Container Registry 身份验证。