為 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，然後 使用聯合身分登入 gcloud CLI。登入後，執行下列指令來初始化 Google Cloud CLI：

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

總覽

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

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

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

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

產生驗證權杖

如要在 Artifact Registry 中驗證套件，必須先產生驗證權杖。之後，您從套件向 Artifact Registry 發出要求時，即可使用這個權杖。

您可以使用 oauth2 產生存取權杖，或在 oauth2l 外部產生權杖。 Google Cloud 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」。

後續步驟