为 Ruby gem 代码库配置向 Artifact Registry 的身份验证

本页面介绍如何配置与 Artifact Registry Ruby gem 代码库的身份验证。

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

您无需为 Cloud Build 或 Google Cloud运行时环境（例如 Google Kubernetes Engine 和 Cloud Run）配置身份验证。

准备工作

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

  4. 安装 Google Cloud CLI，然后 使用联合身份登录 gcloud CLI。 登录后，运行以下命令来初始化 Google Cloud CLI： 

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

概览

Ruby 支持两种方法来对向 Artifact Registry 代码库发出的请求进行身份验证：

  • RubyGems CLI：支持推送和拉取请求。此 CLI 默认随 Ruby 提供。使用 RubyGems 进行身份验证时，您每次向代码库发出推送或拉取请求时都必须进行身份验证。

  • Bundler CLI：支持拉取请求。Bundler 会将软件包和上游存储在 Gemfile 中，这让用户能够标准化多台机器上的设置，而无需对每个单独的拉取请求进行身份验证。不过，您仍需偶尔重新向 Bundler 验证凭据。

    如需安装 Bundler CLI，请输入 gem install bundler。

生成用于身份验证的令牌

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

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

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

使用 gcloud 生成令牌

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

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

现在，您可以通过 Ruby 软件包向 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 变量中。现在，当您从 Ruby 软件包向 Artifact Registry 发出请求时，可以引用 ACCESS_TOKEN。

使用 RubyGems CLI 进行身份验证

RubyGems CLI 使用 OAuth2 令牌对请求进行身份验证。如需将 OAuth2 令牌传递给对 Artifact Registry 代码库的调用，您必须在发出请求时，将 OAuth2 令牌与代码库的地址一起传递。令牌的有效期为 1 小时，必须每小时刷新一次。

对拉取请求进行身份验证

您可以在 Google Cloud CLI 命令行中或通过更新 .gemrc 文件来对拉取请求进行身份验证。

在命令行中对拉取请求进行身份验证

如需对拉取请求中的 gem 的最新版本进行身份验证，请运行以下命令：

gem install GEM_NAME --source https://$ACCESS_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

如需针对特定 gem 版本进行身份验证，请将 -v GEM_VERSION 添加到 gem install 命令。

其中：

  • GEM_NAME 是相应请求所针对的 gem 的名称。
  • LOCATION 是代码库的单区域或多区域位置。
  • PROJECT 是包含相应代码库的项目的 ID。
  • REPOSITORY 是代码库的 ID。

在 .gemrc 文件中进行身份验证

您可以配置全局或项目特定的 /.gemrc 文件，以通过添加以下内容来对拉取请求中的来源进行身份验证：

# File: ~/.gemrc

# Use the ACCESS_TOKEN retrieved from export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://ACCESS_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY/
<...>

其中：

  • ACCESS_TOKEN 是您的 OAuth2 访问令牌。
  • LOCATION 是代码库的单区域或多区域位置。
  • PROJECT 是包含相应代码库的项目的 ID。
  • REPOSITORY 是代码库的 ID。

如需使用 /.gemrc 文件中定义的来源安装 gem，请运行以下命令：

gem install GEM_NAME

对推送请求进行身份验证

您可以在 Google Cloud CLI 命令行中或通过更新凭据文件来对推送请求进行身份验证。

在命令行中对推送请求进行身份验证

如需对推送请求进行身份验证，请运行以下命令：

export GEM_HOST_API_KEY="Bearer $(gcloud auth print-access-token)"
gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

其中：

  • GEM_NAME 是相应请求所针对的 gem 的名称。
  • LOCATION 是代码库的单区域或多区域位置。
  • PROJECT 是包含相应代码库的项目的 ID。
  • REPOSITORY 是代码库的 ID。

在凭据文件中对推送请求进行身份验证

gem 命令行工具使用 ~/.gem/credentials 文件来存储用于推送和拉取 gem 的 API 密钥。如需将凭据文件配置为在推送请求中向来源进行身份验证，请执行以下操作：

  1. 更新凭据文件：

    1. 打开 ~/.gem/credentials 并为您的代码库添加一行代码。键是您的代码库网址，值是 Bearer，后跟您的令牌：

      :rubygems_api_key: RUBYGEMS_ORG_KEY
https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY: Bearer ACCESS_TOKEN

      其中：

      • RUBYGEMS_ORG_KEY 是 RubyGems.org 的 API 密钥。
      • LOCATION 是代码库的单区域或多区域位置。
      • PROJECT 是包含相应代码库的项目的 ID。
      • REPOSITORY 是代码库的 ID。
      • ACCESS_TOKEN 是您的 OAuth2 访问令牌。

    2. 推送 Gem。请注意，您无需设置 GEM_HOST_API_KEY，因为您已在凭据文件中定义了该密钥。

      gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

使用 Bundler 进行身份验证

Ruby Bundler 可跨一个或多个 gem 管理应用依赖项。如需设置 Bundler，请执行以下操作：

  1. 在 Gemfile 中将代码库的地址添加为 source：

    # Gemfile
# <...>
source "https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"

  2. 使用 bundle config 向代码库进行身份验证：

    export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
export HOST="https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"
bundle config $HOST $GEM_TOKEN

其中：

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

您需要偶尔重新对远程代码库进行身份验证。在这种情况下，请运行第 2 步中的同一身份验证命令。

如需详细了解如何配置 Bundler，请参阅 bundler.io 文档中的 Gemfiles。

后续步骤