身份验证方法

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

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

准备工作

  1. 您用于身份验证的帐号必须具有访问该注册表的权限。我们建议您使用服务帐号,而不是用户帐号。服务帐号与特定用户无关,Google Cloud 应用可以使用应用默认凭据策略自动获取凭据。

  2. 安装最新版本的 Cloud SDK。如需更新现有安装,请运行命令 gcloud components update

  3. Docker 要求凭据帮助程序位于系统 PATH 中。确保 gcloud 命令位于系统 PATH 中。

  4. 安装 Docker(如果尚未安装)。

  5. Docker 需要特别访问权限才能与注册表进行交互。 如果在 Linux 或 Windows 上安装了 Docker,请将您用于运行 Docker 命令的用户添加到 Docker 安全群组。

    在 MacOS 上,Docker 从虚拟机以 root 用户身份运行,因此不需要执行此步骤。如需详细了解 MacOS 上的 Docker,请参阅 Docker 文档

    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 或更高版本。
独立 Docker 凭据帮助程序
此选项主要用于配置凭据,以便在没有 Cloud SDK 时配合 Docker 使用。此选项仅支持 Docker 版本 18.03 或更高版本。
访问令牌
应用默认凭据提供服务帐号用于访问 Google Cloud 资源的短期访问令牌。 使用 gcloud 作为凭证帮助程序是最安全的选择。
JSON 密钥文件

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

请尽可能使用访问令牌或其他可用的身份验证方法,以降低未经授权而访问工件的风险。如果必须使用服务帐号密钥,请务必按照管理凭据的最佳做法操作。

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

凭据帮助程序

Docker 凭据帮助程序将 Docker 配置为使用特定注册表进行身份验证。Container Registry 会提供:

  • gcloud 凭据帮助程序
  • 适用于 Cloud SDK 不可用的系统的独立凭据帮助程序

gcloud Docker 凭据帮助程序

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

使用 gcloudCloud Shell 或安装了Cloud SDK 的任何环境中配置身份验证。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 的服务帐号名称。您可以在 Cloud Console 的服务帐号页面上查看现有服务帐号,也可以使用命令 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 现已配置为向 Container Registry 进行身份验证。如需推送和拉取映像,请确保正确配置权限

独立 Docker 凭据帮助程序

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

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

如需配置身份验证,请执行以下操作:

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

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

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

    VERSION=2.0.0
    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 --to-stdout ./docker-credential-gcr \
    > /usr/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr
    
  3. 使用以下命令配置 Docker:

    docker-credential-gcr configure-docker
    

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

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

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

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

访问令牌

访问令牌是一种短期凭据,用于提供对 Google Cloud 资源的访问权限。您可以使用访问令牌作为密码来关联到 Container Registry。

Google Cloud 使用应用默认凭据获取访问令牌。

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

    控制台

    1. 在 Google Cloud Console 中,打开创建服务帐号密钥页面。

      转到“创建服务帐号密钥”页面

    2. 从“服务帐号”列表中,选择您要使用的服务帐号。

      要创建新的服务帐号,请选择新的服务帐号并根据您要授予服务帐号的权限来指定服务帐号名称、ID 和适当的 Container Registry 角色

    3. 选择 JSON 作为密钥类型。

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

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

    gcloud

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

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

      gcloud iam service-accounts create NAME
      
    2. 向服务帐号授予权限。将 PROJECT_ID 替换为项目 ID,并将 ROLE 替换为服务帐号的相应 Container Registry 角色。此角色适用于项目中的所有代码库。 您可以稍后更改该角色,还可以为特定代码库上的服务帐号设置不同的权限。

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. 生成密钥文件。此页面上的说明使用密钥文件的文件名 keyfile.json

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
      
  2. 运行以下命令,以服务帐号的身份登录 Cloud SDK。

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

    其中

    • ACCOUNT 是格式为 [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com 的服务帐号名称。
    • KEY-FILE 是服务帐号密钥文件。如需了解如何创建密钥,请参阅 IAM 文档
  3. 验证是否为服务帐号正确配置了权限。如果您使用的是 Compute Engine 服务帐号,则必须正确配置权限和访问权限范围。

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

    Linux/macOS

    • 用户名oauth2accesstoken
    • 密码是您的访问令牌。例如 gcloud auth print-access-token

    例如:

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

    其中 [HOSTNAME]gcr.ious.gcr.ioeu.gcr.ioasia.gcr.io

    或者,对于不支持 --password-stdin 的旧版 Docker 客户端,请使用以下命令:

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://[HOSTNAME]
    

    Windows

    • 用户名oauth2accesstoken
    • 密码gcloud auth print-access-token 的输出
    1. 获取访问令牌
    gcloud auth print-access-token
    

    返回的字符串是您用作密码的访问令牌。 在此示例中,ya29.8QEQIfY_... 表示返回的访问令牌。

    ya29.8QEQIfY_...
    
    1. 使用访问令牌登录
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://[HOSTNAME]
    

    其中 [HOSTNAME]gcr.ious.gcr.ioeu.gcr.ioasia.gcr.io

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

JSON 密钥文件

服务帐号密钥是长期有效的密钥对,您可以将其用作服务帐号的凭据。您负责私钥的安全性和其他密钥管理操作,例如密钥轮替。

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

此外,密钥访问服务帐号(以及服务帐号可访问的数据)的生命周期与已下载密钥的用户的生命周期无关。

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

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

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

  1. 创建用于与代码库进行交互的服务帐号:

    控制台

    1. 在 Google Cloud Console 中,打开创建服务帐号密钥页面。

      转到“创建服务帐号密钥”页面

    2. 从服务帐号列表中,选择新的服务帐号

    3. 服务帐号名称字段中,输入一个名称。

    4. 角色列表中,为服务帐号选择合适的 Container Registry 角色

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

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

    gcloud

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

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

      gcloud iam service-accounts create NAME
      
    2. 向服务帐号授予权限。将 PROJECT_ID 替换为项目 ID;将 ROLE 替换为服务帐号的相应角色

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. 生成密钥文件。在此示例中,输出密钥文件名为 keyfile.json

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
      
  2. 验证是否为服务帐号正确配置了权限。如果您使用的是 Compute Engine 服务帐号,则必须正确配置权限和访问权限范围。

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

    Linux/macOS

    • 用户名_json_key(不是您的服务帐号名称)
    • keyfile.json 是您创建的服务帐号密钥

    例如:

    cat keyfile.json | docker login -u _json_key --password-stdin https://[HOSTNAME]
    

    其中 [HOSTNAME]gcr.ious.gcr.ioeu.gcr.ioasia.gcr.io

    或者,对于不支持 --password-stdin 的旧版 Docker 客户端,请使用以下命令:

    docker login -u _json_key -p "$(cat keyfile.json)" https://[HOSTNAME]
    

    其中 [HOSTNAME]gcr.ious.gcr.ioeu.gcr.ioasia.gcr.io

    Windows

    • 用户名_json_key(不是您的服务帐号名称)
    • keyfile.json 包含服务帐号 JSON 密钥。

    例如:

    docker login -u _json_key --password-stdin https://[HOSTNAME] < keyfile.json
    

    其中 [HOSTNAME]gcr.ious.gcr.ioeu.gcr.ioasia.gcr.io

    或者,对于不支持 --password-stdin 的旧版 Docker 客户端,请使用以下命令:

    set /p PASS=<keyfile.json
    docker login -u _json_key -p "%PASS%" https://[HOSTNAME]
    

    其中 [HOSTNAME]gcr.ious.gcr.ioeu.gcr.ioasia.gcr.io

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