为 Python 软件包代码库设置身份验证

本页面介绍如何使用 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 命令配置默认值。

概览

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 等工具进行引用。
- 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 中将密钥环与您的用户凭据搭配使用。在连接到 Python 软件包代码库之前，请登录 Google Cloud CLI。

运行以下命令：

gcloud auth login

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

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

创建服务帐号，或选择用于自动化服务的现有服务帐号。
向服务帐号授予适当的 Artifact Registry 角色，以提供代码库访问权限。
使用以下方法之一向您的服务帐号进行身份验证：
- 应用默认凭据（推荐）
  
  将服务帐号密钥文件分配给变量 GOOGLE_APPLICATION_CREDENTIALS，以便 Artifact Registry 凭据帮助程序可在与代码库连接时获取您的密钥。
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
- gcloud 凭据
  
  在连接到代码库之前，请以服务帐号的身份登录。如果您要从 Compute Engine 虚拟机连接到代码库，请勿使用此选项，因为 Artifact Registry 会在 gcloud 中的凭据之前找到虚拟机服务帐号凭据。
```
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 等工具进行引用。
- 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。