在 Artifact Registry 中儲存 Ruby Gem

在 Artifact Registry 中儲存 Ruby Gem

預先發布版

這項產品或功能 適用《服務專屬條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本快速入門導覽課程說明如何設定私人的 Artifact Registry Ruby 存放區，然後將套件 (也稱為 gem) 上傳至該存放區。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
Make sure that you have the following role or roles on the project: Artifact Registry Administrator
Check for the roles
1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
1. In the Google Cloud console, go to the IAM page.

   前往「IAM」
2. 選取所需專案。
3. 點選 「Grant access」(授予存取權)。

4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是指 Google 帳戶的電子郵件地址。

5. 在「Select a role」(選取角色) 清單中選取角色。
6. 如要授予其他角色，請按一下 「Add another role」(新增其他角色)，然後新增角色。
7. 按一下「Save」(儲存)。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Make sure that you have the following role or roles on the project: Artifact Registry Administrator

Check for the roles

1. In the Google Cloud console, go to the IAM page.

   Go to IAM
2. Select the project.

3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

Grant the roles

1. In the Google Cloud console, go to the IAM page.

   前往「IAM」
2. 選取所需專案。
3. 點選 「Grant access」(授予存取權)。

4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。 這通常是指 Google 帳戶的電子郵件地址。

5. 在「Select a role」(選取角色) 清單中選取角色。
6. 如要授予其他角色，請按一下 「Add another role」(新增其他角色)，然後新增角色。
7. 按一下「Save」(儲存)。

啟動 Cloud Shell

在本快速入門導覽課程中，您將使用 Cloud Shell，這是用來管理Google Cloud上託管資源的殼層環境。

Cloud Shell 已預先安裝 Google Cloud CLI 和 Ruby。gcloud CLI 提供 Google Cloud的主要指令列介面。

啟動 Cloud Shell：

1. 前往 Google Cloud 控制台。

   Google Cloud console

2. 在 Google Cloud 控制台工具列中，按一下「啟用 Cloud Shell」。

此時 Cloud Shell 工作階段會在主控台底部的頁框中開啟，您可以使用這個殼層來執行 gcloud 指令。

設定驗證機制

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://$[e-mail]/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://[e-mail]/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_HOST_API_KEY 後，推送要求就不必在網址中傳遞 OAuth2 權杖。

其中：

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

如要進一步瞭解驗證方式，請參閱「為 Ruby Gem 存放區設定 Artifact Registry 驗證」。

建立存放區

為 Gem 建立存放區。

1. 執行下列指令，以便在 us-west1 位置中的 quickstart-ruby-repo 當前專案內建立新的 Ruby Gem 存放區。

   gcloud artifacts repositories create quickstart-ruby-repo \
       --repository-format=ruby \
       --location=us-west1 \
       --description="Ruby gem repository"
   

2. 執行下列指令來確認存放區已建立完成：

   gcloud artifacts repositories list
   

3. 如要簡化 gcloud 指令，請將預設存放區設為 quickstart-ruby-repo，預設位置設為 us-west1。 設定值後，您不需要在需要存放區或位置的 gcloud 指令中指定這些值。

   如要設定存放區，請執行下列指令：

   gcloud config set artifacts/repository quickstart-ruby-repo
   

   如要設定位置，請執行下列指令：

   gcloud config set artifacts/location us-west1
   

   如要進一步瞭解這些指令，請參閱 gcloud config set 說明文件。

下載 Gem

建構 Ruby 專案時，發布檔案會儲存在 Ruby 專案的 lib 子目錄中。為簡化本快速入門導覽課程，您將建立目錄，然後將 Gem 下載到該目錄。

如要建立目錄，請執行下列指令：

mkdir ruby-quickstart
mkdir ruby-quickstart/lib
cd ruby-quickstart/lib

接著下載 Gem。你可以使用自己的 Gem，也可以從 rubygems.org 的熱門 Gem 頁面下載範例 Gem。如要從 rubygems.org 下載 Gem，請執行下列指令：

gem fetch GEM_NAME

ruby_quickstart/lib 目錄中現在有「GEM_NAME」寶石。在下一節中，您將使用 RubyGems CLI 將 Gem 推送至存放區。

將 Gem 推送至存放區

如要將 Gem 推送到存放區，請執行下列指令：

gem push GEM_NAME --host https://us-west1-ruby.pkg.dev/PROJECT/quickstart-ruby-repo

其中：

• GEM_NAME 是要推送至存放區的 Gem 名稱。
• PROJECT 是專案 ID。如果省略這個標記，系統會使用目前的或預設專案。

查看存放區中的 Gem

如要確認寶石已新增，請列出 ruby-quickstart 存放區中的套件。

執行下列指令：

gcloud artifacts packages list --repository=ruby-quickstart

如要查看 Gem 的版本，請執行下列指令：

gcloud artifacts versions list --package=GEM_NAME

安裝 Gem

如要安裝剛推送到 Artifact Registry 存放區的 Gem，請執行下列指令：

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$[e-mail]/PROJECT/quickstart-ruby-repo

其中：

• GEM_NAME 是要在存放區中安裝的 Gem 名稱。
• PROJECT 是專案 ID。如果省略這個標記，系統會使用目前的或預設專案。

疑難排解

詳情請參閱「Ruby Gem 的疑難排解」。

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請按照下列步驟操作。

移除存放區之前，請先確認要保留的 Gem 均已存放於其他位置。

1. 如要刪除 quickstart-ruby-repo 存放區，請執行下列指令：

   gcloud artifacts repositories delete quickstart-ruby-repo
   

2. 如要移除您為使用中的 gcloud 設定建立的預設存放區和位置設定，請執行下列指令：

   gcloud config unset artifacts/repository
   gcloud config unset artifacts/location
   

後續步驟

• 進一步瞭解如何設定驗證方法
• 瞭解如何管理存放區
• 瞭解如何管理套件
• 參閱開發運作相關資源，並探索我們的研究計畫。