为 Docker 设置身份验证

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

准备工作

  1. 快速确认您已启用 Artifact Registry API 并安装 Cloud SDK。如需相关说明,请参阅启用和停用服务
  2. 如果目标代码库不存在,请创建新代码库
  3. (可选)为 gcloud 命令配置默认值
  4. 安装 Docker(如果尚未安装)。Cloud Shell 中包含 Docker。
  5. 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 是您的用户名。

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

选择身份验证方法

在大多数情况下,我们建议您使用服务帐号进行 Artifact Registry 身份验证。

服务帐号与特定用户无关联,Google Cloud 应用可以使用应用默认凭据策略自动获取凭据。

通常与 Artifact Registry 集成的应用(例如 Cloud Build 或 Cloud Run)的服务帐号默认配置了可以访问同一项目中的代码库的权限。您无需为这些应用配置 Docker 身份验证。

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

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

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

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

只有在使用 gcloud 凭据帮助程序,并且了解使用其他选项的安全隐患时,才应选择其中一个备用身份验证方案。

此外,请考虑已授予用于连接到 Artifact Registry 的用户帐号或服务帐号的权限。例如,Compute Engine 默认服务帐号具有父项目的 Editor 基本角色。请考虑创建一个具备使用代码库所需的特定权限的服务帐号,而不是使用默认服务帐号与代码库进行交互。

gcloud 凭据帮助程序(推荐)

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

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

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

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

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

      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. 运行以下命令:

    gcloud auth configure-docker HOSTNAME-LIST
    

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

    例如,如需添加区域 us-central1asia-northeast1,请运行以下命令:

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

    指定的代码库位置将添加到凭据帮助程序配置中。稍后,您可以通过再次运行该命令,将其他位置添加到该配置中。

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

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

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

独立凭据帮助程序

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

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

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

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

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

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

    VERSION=2.0.0
    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 --to-stdout ./docker-credential-gcr \
    > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
    
  3. 将 Docker 配置为使用 Artifact Registry 凭据与 Artifact Registry 进行交互(您只需执行此操作一次):

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

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

    例如,如需添加区域 us-central1asia-northeast1,请运行以下命令:

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

    指定的代码库位置将添加到凭据帮助程序配置中。稍后,您可以通过再次运行该命令,将其他位置添加到该配置中。

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

    gcloud artifacts locations list
    

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

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

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

访问令牌

访问令牌是一种短期令牌,用于提供对 Google Cloud 资源的访问权限。由于令牌在 60 分钟内有效,因此请在使用它连接 Artifact Registry 存储库之前一个小时内申请。

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

如需使用访问令牌,请执行以下操作:

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

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

    转到“服务帐号”页面

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

  3. 在使用 Docker 进行 Artifact Registry 身份验证时,获取访问令牌作为凭据。

    Linux/macOS

    运行以下命令:

    gcloud auth print-access-token | docker login -u oauth2accesstoken \
    --password-stdin https://LOCATION-docker.pkg.dev
    

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

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" \
    https://LOCATION-docker.pkg.dev
    

    其中

    • oauth2accesstoken 是在使用访问令牌进行身份验证时要使用的用户名。
    • gcloud auth print-access-token 是用于获取访问令牌的 gcloud 命令。您的访问令牌是进行身份验证的密码。
    • LOCATION 是存储映像的代码库所在的单区域或多区域位置

    Windows

    运行以下命令:

    gcloud auth print-access-token
    ya29.8QEQIfY_...
    
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
    https://LOCATION-docker.pkg.dev/<var>PROJECT-ID</var>/<var>REPOSITORY</var>
    

    其中

    • oauth2accesstoken 是在使用访问令牌进行身份验证时要使用的用户名。
    • gcloud auth print-access-token 是用于获取访问令牌的 gcloud 命令。您的访问令牌是进行身份验证的密码。
    • LOCATION 是存储映像的代码库所在的单区域或多区域位置

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

JSON 密钥文件

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

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

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

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

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

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

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

    转到“服务帐号”页面

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

    Linux

    base64 FILE-NAME &gt; NEW-FILE-NAME
    

    macOS

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

    Windows

    Base64.exe -e FILE-NAME &gt; 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
    

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

    docker login -u KEY-TYPE -p "$(cat FILE-NAME.json)" \
    https://LOCATION-docker.pkg.dev
    

    其中

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

    Windows

    运行以下命令:

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

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

    set /p PASS=<KEY-FILE
    docker login -u KEY-TYPE -p "%PASS%" https://LOCATION-docker.pkg.dev
    

    其中

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

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