为 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
```
注意：如果您之前安装了 gcloud CLI，请确保通过运行 gcloud components update 获得最新版本。
（可选）为 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 会按以下顺序搜索凭据：

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

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

正在设置密钥环

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

安装密钥环库。
```
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 凭据
  
  在连接到代码库之前，请以服务帐号的身份登录。由于 Artifact Registry 会在 gcloud CLI 中的凭据之前找到虚拟机服务帐号凭据，因此如果您要从 Compute Engine 虚拟机连接到代码库，请避免使用此选项。
```
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。