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

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

您无需为 Cloud Build 或 Google Cloud 运行时环境（例如 Google Kubernetes Engine 和 Cloud Run）配置身份验证，但应验证是否已配置所需权限。

准备工作

安装 Google Cloud CLI，然后通过运行以下命令初始化 Google Cloud CLI：
```
gcloud init
```
（可选）为 gcloud CLI 命令配置默认值。
确认您用于身份验证的帐号具有访问 Artifact Registry 的权限。建议使用服务帐号，而不是用户帐号。
安装 Docker（如果尚未安装）。Cloud Shell 中包含 Docker。
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 是您的用户名。
退出并重新登录以使群组成员资格变更生效。如果您使用的是虚拟机，则可能需要重启虚拟机才能使成员资格变更生效。

注意：Docker 安全群组具有的访问权限相当于 root 用户或管理员用户。仅添加需要访问 Docker 的可信用户。如需详细了解安全性影响，请参阅 Docker 守护程序安全性。

选择身份验证方法

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

gcloud CLI 凭据帮助程序: 直接在 gcloud CLI 中配置用于 Docker 的 Artifact Registry 凭据。这是最简单的身份验证方法，但可能比独立凭据帮助程序慢。
独立 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，使其在任何安装了 Google Cloud CLI 的环境中向 Artifact Registry 主机进行身份验证。Cloud Shell 包含 Google Cloud CLI 和当前版本的 Docker。

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

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

以将运行 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) 文档。
  注意：如果管理不当，服务帐号密钥会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性以及管理服务账号密钥的最佳实践中所述的其他操作。如果系统阻止您创建服务账号密钥，您的组织可能会停用服务账号密钥创建功能。如需了解详情，请参阅管理默认安全的组织资源。
运行以下命令：
```
gcloud auth configure-docker HOSTNAME-LIST
```
其中 HOSTNAME-LIST 是要添加到凭据帮助程序配置的以英文逗号分隔的代码库主机名列表。

例如，如需添加区域 us-central1 和 asia-northeast1，请运行以下命令：
```
gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
```
指定的主机名会添加到凭据帮助程序配置中。稍后您可以通过再次运行该命令将其他主机名添加到配置中。

如需查看受支持的代码库位置列表，请运行以下命令：
```
gcloud artifacts locations list
```
添加指定主机名后，该命令会显示当前 Docker 配置的 credHelpers 部分以及更新后的配置。

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

凭据会保存在用户的主目录中。
- Linux：$HOME/.docker/config.json
- Windows：%USERPROFILE%/.docker/config.json
Docker 要求凭据帮助程序位于系统 PATH 中。确保 gcloud 命令位于系统 PATH 中。

独立凭据帮助程序

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

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

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

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

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

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

VERSION=2.1.22
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/

将 Docker 配置为使用 Artifact Registry 凭据与 Artifact Registry 进行交互（您只需执行此操作一次）：
```
docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
```
其中 HOSTNAME-LIST 是要添加到凭据帮助程序配置的以英文逗号分隔的代码库主机名列表。

例如，如需添加区域 us-central1 和 asia-northeast1，请运行以下命令：
```
docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
```
指定的主机名会添加到凭据帮助程序配置中。稍后您可以通过再次运行该命令将其他主机名添加到配置中。

如需查看受支持的代码库位置列表，请运行以下命令：
```
gcloud artifacts locations list
```
如需了解详情，请参阅 GitHub 上的独立 Docker 凭据帮助程序文档。

注意：如果您通常使用 sudo 在 Linux 上运行 Docker 命令，Docker 会在/root/.docker/config.json（而非 $HOME/.docker/config.json）中查找 Artifact Registry 凭据。如果您要搭配使用 sudo 与 docker 命令而不是使用 Docker 安全群组，请改为使用 sudo docker-credential-gcr configure-docker 配置凭据。

凭据会保存在用户的主目录中。
- Linux：$HOME/.docker/config.json
- Windows：%USERPROFILE%/.docker/config.json
Docker 要求凭据帮助程序位于系统 PATH 中。确保 docker-credential-gcr 命令位于系统 PATH 中。
如需验证凭据帮助程序是否可以成功检索您的凭据，请运行以下命令：
```
echo "https://HOSTNAME" | docker-credential-gcr get
```
将 HOSTNAME 替换为您添加到配置的主机名。例如：
```
echo "https://us-central1-docker.pkg.dev" | docker-credential-gcr get
```
如果命令成功，返回的 JSON 输出会在 Secret 字段中包含令牌。例如：
```
{"ServerURL":"https://us-central1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
```

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

访问令牌

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

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

创建一个服务帐号代表您的应用执行操作，或者选择一个用于自动化的现有服务帐号。
向服务帐号授予特定的 Artifact Registry 角色，以提供代码库访问权限。
为服务帐号生成访问令牌并进行身份验证：
- 您必须拥有 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 代码库的新服务账号和服务账号密钥，请执行以下操作：

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

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

转到“服务账号”页面

注意：如果服务账号密钥未正确管理，则会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性以及管理服务账号密钥的最佳实践中所述的其他操作。如果系统阻止您创建服务账号密钥，您的组织可能会停用服务账号密钥创建功能。如需了解详情，请参阅管理默认安全的组织资源。
您可以选择性地对密钥文件的所有内容采用 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 编码的密钥文件。
验证是否为服务账号正确配置了权限。如果您使用的是 Compute Engine 服务账号，则必须正确配置权限和访问权限范围。
使用服务账号密钥来配置与 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 身份验证。

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

准备工作

Linux

Windows

选择身份验证方法

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

gcloud CLI 凭据帮助程序

独立凭据帮助程序

访问令牌

Linux

Windows

服务账号密钥

Linux

macOS

Windows

Linux/macOS

Windows