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

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

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

对于 Python 软件包仓库，Artifact Registry 支持以下身份验证方法：

• 访问令牌：在自动化、CI/CD 流水线、容器构建或不支持安装密钥环库的环境中使用访问令牌。
• Python Keyring 库（建议用于本地开发）：在开发者工作站上使用此选项可自动处理凭据刷新。
• 密码身份验证：如果应用不支持应用默认凭据，但支持使用用户名和密码进行身份验证，请使用此选项。

准备工作

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

4. 安装 Google Cloud CLI。 安装完成后，运行以下命令来初始化 Google Cloud CLI：

   gcloud init

   如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

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

生成用于身份验证的令牌

如需在 Artifact Registry 中对软件包进行身份验证，您必须先生成身份验证令牌。然后，您可以在从软件包向 Artifact Registry 发出请求时使用此令牌。

您可以使用 Google Cloud 生成 oauth2 访问令牌，也可以在 Google Cloud之外生成 oauth2l 令牌。

访问令牌的有效期为 60 分钟。在运行与代码库互动的命令之前不久生成访问令牌。如果您的访问令牌已过期，您必须生成新的访问令牌。

使用 gcloud 生成令牌

如需使用 Google Cloud生成 oauth2 访问令牌，请运行以下命令：

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

现在，当您从 Python 软件包向 Artifact Registry 发出请求时，可以引用 ACCESS_TOKEN。

在不使用 gcloud 的情况下生成令牌

如需仅使用 oauth2l CLI 生成访问令牌，请执行以下操作：

1. 运行以下命令，安装最新版本的 oauth2l：

   go install github.com/google/oauth2l@latest
   

2. 运行以下命令：

   export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"
   

   Google Cloud 生成 SHA256 哈希令牌并将其存储在 ACCESS_TOKEN 变量中。现在，当您从 Python 软件包向 Artifact Registry 发出请求时，可以引用 ACCESS_TOKEN。

使用 pip 进行身份验证

导出 ACCESS_TOKEN 后，您可以将其传递给 pip 以安装软件包：

pip install PACKAGE --index-url https://$[e-mail]/PROJECT/REPOSITORY/simple/

使用密钥环进行身份验证

Python 密钥环库为应用提供了一种访问密钥环后端（即操作系统和第三方凭据存储区）的方式。Artifact Registry 提供 keyrings.google-artifactregistry-auth 密钥环后端，用于处理与 Artifact Registry 代码库的身份验证。

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

凭据搜索顺序

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

运行以下命令：

gcloud auth login

注意： Artifact Registry 会按特定顺序搜索凭据。如果先找到服务账号凭据，则使用这些凭据，而不是您的用户凭据。

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

设置密钥环后，您可以设置用于身份验证的服务账号。

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 文件中。每个用户的 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 编码密钥。

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:[e-mail]/PROJECT/REPOSITORY/simple/
   

   • KEY 服务账号密钥文件中的私钥。
   • 代码库路径末尾的 /simple/ 字符串表示该代码库实现了 Python Simple Repository API。

后续步骤

• 配置对代码库的访问权限
• 了解如何管理代码库
• 了解如何管理软件包