為 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。

產生權杖以進行驗證

如要在 Artifact Registry 中驗證套件，必須先產生驗證權杖。接著，您就能在從套件向 Artifact Registry 提出要求時使用這個權杖。

您可以使用 oauth2 權杖或 Google Cloud 權杖，在 oauth2l 外部產生存取權杖 Google Cloud。

存取權杖的效期為 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 權杖和存放區的位址。權杖的效期為一小時，因此必須每小時重新整理一次。

驗證提取要求

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

透過指令列驗證提取要求

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

gem install GEM_NAME --source https://$ACCESS_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 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 檔案儲存 API 金鑰，用於推送及提取 Gem。如要設定憑證檔案，以便在推送要求時驗證來源，請按照下列步驟操作：

  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_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」。

後續步驟