为 Docker 配置对 Artifact Registry 的身份验证

本页介绍了如何配置 Docker 以对 Artifact Registry Docker 代码库进行身份验证。

您无需为 Cloud Build 或 Google Cloud 配置身份验证 Google Kubernetes Engine 和 Cloud Run等运行时环境，但您应该 验证所需的权限 配置。

准备工作

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  2. （可选）为 gcloud CLI 命令配置默认值。
  3. 验证用于身份验证的账号是否具有访问 Artifact Registry 的权限。我们建议使用服务账号，而不是 与用户账号相比
  4. 安装 Docker（如果尚未安装）。 Cloud Shell 中包含 Docker。

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

    Linux

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

    sudo usermod -a -G docker ${USER}

    Windows

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

    net localgroup docker-users DOMAIN\USERNAME /add

    其中

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

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

选择身份验证方法

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

gcloud CLI 凭据帮助程序
配置 Artifact Registry 凭据，以便直接在 gcloud CLI 中配合 Docker 使用。这是最简单的身份验证方法，但速度可能比独立凭据帮助程序慢。
独立 Docker 凭据帮助程序
此选项主要用于配置凭据，以便在没有 Google Cloud CLI 时配合 Docker 使用。它比 gcloud CLI 凭据帮助程序快得多，并使用应用默认凭据 (ADC) 自动查找环境中的凭据。
访问令牌
您可以为服务账号生成短期有效的访问令牌，然后使用该令牌进行密码身份验证。由于令牌的有效期只有 60 分钟，因此它比服务账号密钥更安全。
服务账号密钥
用户管理的密钥对，可用作 服务账号。由于它是长期凭据，因此它是所有可用身份验证方法中最不安全的选项。

请尽可能使用访问令牌 或凭据帮助程序，以降低未经授权访问您 容器映像如果必须使用服务账号密钥，请务必按照管理凭据的最佳做法操作。

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

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

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

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

credHelpers
如果您使用 Docker 凭据帮助程序进行身份验证 Artifact Registry 将凭据帮助程序设置存储在 credHelpers 部分。
auths
如果您使用 Docker 以令牌或服务账号密钥作为您的 因此 Docker 会将凭据的 base64 编码版本 auths 部分。
credStore
如果您配置了 凭据存储区 凭据存储区的设置位于 文件的 credStore 部分。

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

gcloud CLI 凭据帮助程序

gcloud CLI 凭据帮助程序可让您在短时间内安全访问项目资源。它会将 Docker 配置为 Artifact Registry 托管在安装了 Google Cloud CLI 的任何环境中。 Cloud Shell 包含 Google Cloud CLI 和最新版本的 Docker。

gcloud CLI 凭据帮助程序是最简单的身份验证设置方法。它使用活跃用户或服务账号的凭据配置 Docker gcloud CLI 会话由于此凭据帮助程序依赖于 gcloud CLI，因此其速度可能会比独立凭据帮助程序慢得多。对于包含 具有大量已配置注册表的第三方工具或 Docker 客户端 请改用独立凭据帮助程序。

如需进行 Artifact Registry 身份验证，请执行以下操作：

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

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

      gcloud auth login

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

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

      地点

      • ACCOUNT 是您要使用的服务账号 Artifact Registry 格式 USERNAME@PROJECT-ID.iam.gserviceaccount.com。 如果您想使用现有账号，可以查看服务列表 账号 服务账号 打开 Google Cloud 控制台 gcloud iam service-accounts list
      • KEY-FILE 是服务账号密钥文件。如需了解如何创建密钥，请参阅 Identity and Access Management (IAM) 文档。

  2. 运行以下命令：

    gcloud auth configure-docker HOSTNAME-LIST

    其中 HOSTNAME-LIST 是以英文逗号分隔的代码库列表 要添加到凭据帮助程序配置的主机名。

    例如，如需添加区域 us-west1 和 asia-northeast1，请运行以下命令：

    gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    指定的主机名将添加到凭据帮助程序配置中。稍后，您可以通过再次运行该命令，将其他主机名添加到该配置中。

    如需查看受支持的代码库位置列表，请运行以下命令：

    gcloud artifacts locations list

  3. 该命令会显示当前 Docker 的 credHelpers 部分 配置和更新后的配置 主机名。

    如需接受配置更改，请输入 y。

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

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

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

独立凭据帮助程序

独立 Docker 凭据帮助程序将 Docker 配置为在 gcloud CLI 不可用的系统上向 Artifact Registry 进行身份验证。它比 gcloud CLI 凭据帮助程序快得多，并使用应用默认凭据 (ADC) 自动查找您环境中的凭据。对于推送和拉取映像以外的操作，例如标记或列出映像。我们建议使用此身份验证方法来进行自动构建，并使用第三方工具或具有大量配置注册表主机的 Docker 客户端。

独立 Docker 凭据帮助程序会提取您的 Artifact Registry 凭据，并将其写入 Docker 配置文件。这样，您就可以使用 Docker 命令行工具 docker 直接与 Artifact Registry 进行交互。

要使用 Docker 凭证帮助程序，请执行以下操作：

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

  2. 从 GitHub 下载独立 Docker 凭据帮助程序。

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

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

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 配置为使用 Artifact Registry 凭据与 Artifact Registry 进行交互（您只需执行此操作一次）：

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

    其中 HOSTNAME-LIST 是以英文逗号分隔的代码库列表 要添加到凭据帮助程序配置的主机名。

    例如，如需添加区域 us-west1 和 asia-northeast1，请运行以下命令：

    docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    指定的主机名将添加到凭据帮助程序配置中。您可以稍后通过运行 命令。

    如需查看受支持的代码库位置列表，请运行以下命令：

    gcloud artifacts locations list

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

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

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

  4. Docker 要求凭据帮助程序位于系统 PATH 中。确保 docker-credential-gcr 命令位于系统 PATH 中。

  5. 如需验证凭据帮助程序能否成功检索您的凭据，请运行以下命令：

    echo "https://HOSTNAME" | docker-credential-gcr get

    将 HOSTNAME 替换为您添加到 配置。例如：

    echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get

    如果命令成功，返回的 JSON 输出中会包含 Secret 字段中的值。例如：

    {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

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

访问令牌

您可以生成短期有效的 OAuth 访问令牌以进行身份验证 Artifact Registry由于令牌的有效期为 60 分钟 您应该在一小时内提出请求，然后再将其用于连接 Artifact Registry

如需将访问令牌与服务账号凭据搭配使用，请执行以下操作：

  1. 创建服务账号代表您的应用执行操作，或选择一个现有服务账号用于进行自动化。

  2. 向服务账号授予特定的 Artifact Registry 角色，以提供代码库访问权限。

  3. 为服务账号生成访问令牌并进行身份验证：

    • 您必须拥有 Service Account Token Creator 角色的权限 （roles/iam.serviceAccountTokenCreator）至 模拟服务账号 以便为该服务账号获取令牌，然后以该服务账号的身份进行身份验证。

      运行以下命令，将 ACCOUNT 替换为您的 服务账号电子邮件地址和 LOCATION 单区域或多区域 的位置 代码库

      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 |
    docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev

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

服务账号密钥

任何有权访问服务账号的有效私钥的人员都可以通过该服务账号访问资源。注意，密钥访问服务账号（以及服务账号可访问的数据）的生命周期与已下载密钥的用户的生命周期无关。

请使用以下准则来限制对代码库的访问：

  • 创建仅用于与代码库进行交互的专用服务账号。
  • 为服务账号所需的访问权限授予特定的 Artifact Registry 角色。例如，仅下载工件的服务账号只需要 Artifact Registry Reader 角色。
  • 在每个代码库（而不是项目级层）上为您的专用服务账号配置权限。然后，您可以根据代码库上下文指定访问权限。例如，用于开发构建的服务账号对于生产代码库可能拥有 Artifact Registry Reader 角色，对于临时代码库可能拥有 Artifact Registry Writer 角色。
  • 按照管理凭据的最佳做法操作。

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

  1. 创建一个服务账号代表您的应用执行操作，或选择一个现有服务账号用于进行自动化。

    您需要服务账号密钥文件所在的位置，才能使用 Artifact Registry 设置身份验证。对于现有账号，您可以在“服务账号”页面上查看密钥和创建新密钥。

    转到“服务账号”页面

  2. 您可以选择性地对密钥文件的所有内容采用 base64 编码。

    Linux

    base64 FILE-NAME > NEW-FILE-NAME

    macOS

    base64 -i FILE-NAME -o NEW-FILE-NAME

    Windows

    Base64.exe -e FILE-NAME > NEW-FILE-NAME

    其中，FILE-NAME 是原始密钥文件名，而 NEW-FILE-NAME 是 base64 编码的密钥文件。

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

  4. 使用服务账号密钥来配置与 Docker 集成：

    运行以下命令：

    Linux/macOS

    cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
https://LOCATION-docker.pkg.dev

    Windows

    Get-Content KEY-FILE |
docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev

    替换以下内容：

    • KEY-TYPE 是以下值之一：
      • 如果您使用的是在创建文件时提供的 JSON 格式的服务账号密钥，则为 _json_key。
      • 如果您已对文件的全部内容进行 base64 编码，则为 _json_key_base64。
    • KEY-FILE 是 JSON 格式的服务账号密钥文件的名称。
    • LOCATION 是 单区域或多区域 代码库的位置 映像存储起来

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