为 Python 软件包代码库配置向 Artifact Registry 的身份验证

本页面介绍了如何使用 Artifact Registry 配置身份验证 Python 软件包代码库。

当您使用第三方应用连接到代码库时，您必须进行 Artifact Registry 身份验证。

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

准备工作

  1. 如果目标代码库不存在，请创建新的 Python 软件包代码库。
  2. 验证是否已安装 Python 3。有关安装说明，请参阅 Google Cloud 设置 Python 教程。
  3. 请确认您使用的用户账号或服务账号拥有 需要权限才能访问 存储库

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

    gcloud init
  5. （可选）为 gcloud CLI 命令配置默认值。

概览

Artifact Registry 支持以下身份验证方法。

Python 密钥库（推荐）
Artifact Registry 提供了一个密钥库后端，用于存储用于连接到 Artifact Registry 仓库的凭据。
密码身份验证
如果您无法使用密钥串，并且需要一个支持基本密码身份验证的选项，请使用此选项。

本文档中的说明介绍了如何将 pip 配置为 pip 搜索软件包的唯一软件包索引。我们建议您使用虚拟代码库在 Artifact Registry 中的私有软件包和 PyPI 中的公共软件包中搜索软件包，而不是在 pip 配置文件中配置多个软件包索引。pip 工具不会按任何特定顺序搜索软件包索引，因此使用方可能会错误地下载或安装与您的某个私有软件包同名的公共软件包。通过虚拟代码库，您可以针对 上游来源，以降低这种依赖项混淆风险。

使用密钥环进行身份验证

Python 密钥环 库为应用提供访问密钥环后端的方式， 操作系统和第三方凭据存储区。

Artifact Registry 提供 keyrings.google-artifactregistry-auth 密钥库后端，用于处理与 Artifact Registry 代码库的身份验证。

凭据搜索顺序

当您使用 Artifact Registry 密钥环后端时，您的凭据 不会存储在您的 Python 项目中。Artifact Registry 会改为按以下顺序搜索凭据：

  1. 应用默认凭据 (ADC) 是一种按以下顺序查找凭据的策略：

    1. 在 GOOGLE_APPLICATION_CREDENTIALS 环境变量中定义的凭据。

    2. Compute Engine 的默认服务账号 Google Kubernetes Engine、Cloud Run、App Engine 或 Cloud Run 函数 提供什么。

  2. Google Cloud CLI 提供的凭据，包括来自命令 gcloud auth application-default login 的用户凭据。

GOOGLE_APPLICATION_CREDENTIALS 变量可让账号 身份验证，从而简化问题排查过程。如果 您未使用该变量，请确认 ADC 可能使用的所有账号 所需的权限。例如， 默认服务账号，用于 Compute Engine 虚拟机、Google Kubernetes Engine 节点 Cloud Run 修订版本拥有对代码库的只读权限。如果您打算使用默认服务账号从这些环境中上传内容，则必须修改权限。

设置密钥环

如需使用 Artifact Registry 密钥串后端设置身份验证，请执行以下操作：

  1. 安装密钥环库。

    pip install keyring

  2. 安装 Artifact Registry 后端。

    pip install keyrings.google-artifactregistry-auth

  3. 列出后端以确认安装。

    keyring --list-backends

    该列表应包含

    • ChainerBackend(priority:10)
    • GooglePythonAuth(priority: 9)

  4. 运行以下命令来输出要添加到 Python 项目的代码库配置。

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

    替换以下值：

    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
    • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
    • LOCATION 是代码库的单区域或多区域位置。

  5. 将以下设置添加到 .pypirc 文件中。默认位置如下：

    • Linux 和 macOS：$HOME/.pypirc
    • Windows：%USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/

    替换以下值：

    • PYTHON-REPO-ID 是代码库的 ID，您可以使用 Twine 等工具引用该 ID。
    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
    • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
    • LOCATION 是代码库的单区域或多区域位置。

  6. 将您的代码库添加到 pip 配置文件中。文件位置取决于您是要更新每位用户的文件，还是要更新特定于您所用虚拟环境的文件。

    对于与您的操作系统用户相关联的文件：

    • Unix：$HOME/.config/pip/pip.conf 或 $HOME/.pip/pip.conf
    • macOS：/Library/Application Support/pip/pip.conf 或 $HOME/.config/pip/pip.conf
    • Windows：%APPDATA%\pip\pip.ini 或 %USERPROFILE%\pip\pip.ini

    对于虚拟环境：

    • Unix 和 macOS：$VIRTUAL_ENV/pip.conf
    • Windows：%VIRTUAL_ENV%\pip.ini

    如需将 pip 配置为仅搜索您的代码库，请使用 index-url 设置，并确保没有使用 extra-index-url 设置配置的其他软件包索引。

    [global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

    存储库路径末尾的 /simple/ 字符串表示该存储库实现了 Python Simple Repository API。

您的 Python 环境现已配置为通过 Artifact Registry 进行身份验证。

使用用户凭据进行密钥环身份验证

设置密钥库后，您可以在 gcloud CLI 中将密钥库与用户凭据搭配使用。请先登录 Google Cloud CLI，然后再连接到 Python 软件包仓库。

运行以下命令：

gcloud auth login

使用服务账号凭据进行密钥环身份验证

设置密钥环后，您便可以设置服务 账号进行身份验证。

  1. 创建一个服务账号，或选择一个现有服务账号用于进行自动化。
  2. 向服务账号授予特定的 Artifact Registry 角色，以提供代码库访问权限。

  3. 使用以下任一选项对服务账号进行身份验证：

    • 应用默认凭据（推荐）

      将服务账号密钥文件分配给变量 GOOGLE_APPLICATION_CREDENTIALS，以便 Artifact Registry 凭据帮助程序可在与代码库连接时获取您的密钥。

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • gcloud CLI 凭据

      在连接到代码库之前，请以服务账号的身份登录。如果您要从 Compute Engine 虚拟机连接到代码库，请避免使用此选项，因为 Artifact Registry 会先找到虚拟机服务账号凭据，然后再找到 gcloud CLI 中的凭据。

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

    将 KEY-FILE 替换为服务账号密钥文件的路径。

使用服务账号密钥进行身份验证

如果您需要使用用户名和密码进行身份验证，请使用此方法。

服务账号密钥是长期有效的凭据。请使用以下准则来限制对代码库的访问：

  • 请考虑使用专用服务账号与代码库进行交互。
  • 授予服务账号所需的最低 Artifact Registry 角色。例如，将 Artifact Registry Reader 分配给仅用于下载工件的服务账号。
  • 如果您组织中的群组需要不同级层的访问权限来访问特定代码库，请在代码库级层而不是项目级层授予访问权限。
  • 按照管理凭据的最佳做法操作。

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

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

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

    转到“服务账号”页面

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

  3. 运行以下命令将代码库配置输出到 添加到 Python 项目中。

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

    替换以下值：

    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
    • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
    • LOCATION 是代码库的单区域或多区域位置。
    • KEY-FILE 是服务账号 JSON 密钥文件的路径。

  4. 将以下设置添加到 .pypirc 文件中。默认位置是 对应的命令为：

    • Linux 和 macOS：$HOME/.pypirc
    • Windows：%USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY

    替换以下值：

    • PYTHON-REPO-ID 是代码库的 ID，您可以使用 Twine 等工具引用该 ID。
    • PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
    • REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则在命令中省略此标志时，系统会使用该代码库。
    • LOCATION 是代码库的单区域或多区域位置。
    • KEY 是服务账号密钥文件中的 base64 编码密钥。

  5. 将您的代码库添加到 pip 配置文件中。通过 pip 配置文件位置 取决于您要更新针对每位用户的文件，还是针对 您正在使用的虚拟环境中

    对于与您的操作系统用户相关联的文件：

    • Unix：$HOME/.config/pip/pip.conf 或 $HOME/.pip/pip.conf
    • macOS：/Library/Application Support/pip/pip.conf 或 $HOME/.config/pip/pip.conf
    • Windows：%APPDATA%\pip\pip.ini 或 %USERPROFILE%\pip\pip.ini

    对于虚拟环境：

    • Unix 和 macOS：$VIRTUAL_ENV/pip.conf
    • Windows：%VIRTUAL_ENV%\pip.ini

    将以下行添加到 pip 配置文件中：

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY 是指您的服务账号密钥文件中的私钥。
    • 代码库路径末尾的 /simple/ 字符串指示 实现了 Python Simple Repository API。

后续步骤