為 Ruby Gem 存放區設定 Artifact Registry 驗證機制

本頁說明如何設定 Artifact Registry Ruby Gem 存放區的驗證。

使用第三方應用程式連線至存放區時，必須向 Artifact Registry 驗證。

您不必為 Cloud Build 或執行階段環境 (例如 Google Kubernetes Engine 和 Cloud Run) 設定驗證。 Google Cloud

事前準備

  1. 如果目標存放區不存在，請建立 Ruby Gem 存放區。
  2. 確認已安裝 Ruby。如需安裝操作說明，請參閱Google Cloud 設定 Ruby 的教學課程。
  3. 確認您使用的使用者帳戶或服務帳戶具備存取存放區的必要權限。

  4. 安裝 Google Cloud CLI。 安裝完成後，請執行下列指令，初始化 Google Cloud CLI： 

    gcloud init

    若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  5. (選用) 設定 gcloud CLI 指令的預設值。

總覽

Ruby 支援兩種方法，可驗證對 Artifact Registry 存放區的要求：

  • RubyGems CLI：支援推送和提取要求。根據預設，這個 CLI 適用於 Ruby。使用 RubyGems 進行驗證時，每次向存放區發出推送或提取要求，都必須進行驗證。

  • Bundler CLI：支援提取要求。Bundler 會將套件和上游儲存在 Gemfile 中，讓使用者在多部電腦上標準化設定，而不需驗證每個個別的提取要求。不過，您仍須不時重新向 Bundler 驗證憑證。

    如要安裝 Bundler CLI，請輸入 gem install bundler。

使用 RubyGems CLI 進行驗證

RubyGems CLI 會使用 OAuth2 權杖驗證要求。如要將 OAuth2 權杖傳遞至對 Artifact Registry 存放區的呼叫，您必須先產生權杖，然後在發出要求時，將權杖連同存放區的位址一併傳遞。權杖的效期為一小時，因此必須每小時更新一次。

驗證提取要求

您可以在 Google Cloud CLI 指令列中驗證提取要求，或更新 .gemrc 檔案。

在指令列中驗證提取要求

如要驗證提取要求中的最新版 Gem，請執行下列指令：

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

如要驗證特定 Gem 版本，請在 gem install 指令中加入 -v GEM_VERSION。

其中：

  • GEM_NAME 是提出要求的 Gem 名稱。
  • LOCATION 是存放區的區域或多區域位置。
  • PROJECT 是包含存放區的專案 ID。
  • REPOSITORY 是存放區的 ID。

在 .gemrc 檔案中進行驗證

您可以在全域或專案專屬的 /.gemrc 檔案中新增下列內容，在提取要求中驗證來源：

# File: ~/.gemrc

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

<...>
:sources:
    - https://GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPO/
<...>

如要使用 /.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 檔案儲存 API 金鑰，以便推送及提取 Gem。如要設定憑證檔案，以便在推送要求中向來源進行驗證，請按照下列步驟操作：

  1. 執行下列指令，產生 OAuth2 存取權杖：

    gcloud auth print-access-token

    這個權杖是 Artifact Registry 的 API 金鑰。

  2. 更新憑證檔案：

    1. 開啟 ~/.gem/credentials，然後為存放區新增一行。鍵是存放區網址，值則是 Bearer，後面接著您的權杖：

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

      其中：

      • RUBYGEMS_ORG_KEY 是 RubyGems.org 的 API 金鑰。
      • LOCATION 是存放區的區域或多區域位置。
      • PROJECT 是包含存放區的專案 ID。
      • REPOSITORY 是存放區的 ID。
      • OAUTH_TOKEN 是您的 OAuth2 存取權杖。

    2. 將寶石推入。請注意，您不需要設定 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」。

後續步驟