此页面由 Cloud Translation API 翻译。

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

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

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

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

准备工作

如果目标代码库不存在，请创建新的 Python 软件包代码库。
验证是否已安装 Python 3。如需查看安装说明，请参阅Google Cloud 有关设置 Python 的教程。
验证您使用的用户账号或服务账号是否具有访问代码库所需的权限。
安装 Google Cloud CLI。安装完成后，运行以下命令来初始化 Google Cloud CLI：
```
gcloud init
```
如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 来获得最新版本。
（可选）为 gcloud CLI 命令配置默认值。

概览

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

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

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

使用密钥环进行身份验证

Python keyring 库为应用提供了一种访问 keyring 后端（即操作系统和第三方凭据存储区）的方式。

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

凭据搜索顺序

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

应用默认凭据 (ADC) 是一种按以下顺序查找凭据的策略：
1. 在 GOOGLE_APPLICATION_CREDENTIALS 环境变量中定义的凭据。
2. Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine 或 Cloud Run 函数的默认服务账号提供的凭据。
Google Cloud CLI 提供的凭据，包括来自命令 gcloud auth application-default login 的用户凭据。

GOOGLE_APPLICATION_CREDENTIALS 变量明确指定了用于身份验证的账号，从而简化了问题排查过程。如果您不使用该变量，请验证 ADC 可能使用的任何账号是否具有所需的权限。例如，Compute Engine 虚拟机、Google Kubernetes Engine 节点和 Cloud Run 修订版本的默认服务账号对仓库具有只读访问权限。如果您打算使用默认服务账号从这些环境中上传，则必须修改权限。

设置密钥环

如需设置与 Artifact Registry 密钥环后端的身份验证，请执行以下操作：

安装 keyring 库。
```
pip install keyring
```

安装 Artifact Registry 后端。

pip install keyrings.google-artifactregistry-auth

列出后端以确认安装。
```
keyring --list-backends
```
该列表应包含
- ChainerBackend(priority:10)
- GooglePythonAuth(priority: 9)
运行以下命令来输出要添加到 Python 项目的代码库配置。
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION
```
替换以下值：
- PROJECT 是项目 ID。如果省略此标志，则系统会使用当前项目或默认项目。
- REPOSITORY 是代码库的 ID。如果您配置了默认 Artifact Registry 代码库，则当您在命令中省略此标志时，系统会使用该代码库。
- LOCATION 是代码库的单区域或多区域位置。
将以下设置添加到 .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 是代码库的单区域或多区域位置。
将您的代码库添加到 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 中将密钥环与用户凭据搭配使用。在连接到 Python 软件包代码库之前，请先登录 Google Cloud CLI。

运行以下命令：

gcloud auth login

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

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

创建一个服务账号，或选择一个现有服务账号用于进行自动化。
向服务账号授予特定的 Artifact Registry 角色，以提供代码库访问权限。
使用以下任一选项通过服务账号进行身份验证：
- 应用默认凭据（推荐）
  
  将服务账号密钥文件分配给变量 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 分配给仅用于下载工件的服务账号。
如果您组织中的群组需要不同级层的访问权限来访问特定代码库，请在代码库级层而不是项目级层授予访问权限。
按照管理凭据的最佳做法操作。

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

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

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

转到“服务账号”页面

注意：如果服务账号密钥未得到适当的管理，则会带来安全风险。您应该尽可能选择更安全的服务账号密钥替代方案。如果必须使用服务账号密钥进行身份验证，您将负责私钥的安全性以及管理服务账号密钥的最佳实践中所述的其他操作。如果系统阻止您创建服务账号密钥，您的组织可能会停用服务账号密钥创建功能。如需了解详情，请参阅管理默认安全的组织资源。
如果您是从外部来源获取服务账号密钥，则必须先验证密钥，然后才能使用。如需了解详情，请参阅外部来源凭据的安全要求。
向服务账号授予适当的 Artifact Registry 角色，以提供代码库访问权限。
运行以下命令来输出要添加到 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 密钥文件的路径。
将以下设置添加到 .pypirc 文件中。每个用户的 pip 配置文件的默认位置为：
- 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 编码密钥。
将您的代码库添加到 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。