Artifact Registry に Ruby gem を保存する

このクイックスタートでは、プライベート Artifact Registry Ruby リポジトリを設定し、パッケージ（gem とも呼ばれます）をそのリポジトリにアップロードする方法について説明します。

始める前に

  1. 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.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. 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.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

必要なロール

Artifact Registry Ruby gem リポジトリの作成と管理に必要な権限を取得するには、プロジェクトに対する Artifact Registry 管理者 （roles/artifactregistry.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Cloud Shell を起動する

このクイックスタートでは、Google Cloudでホストされているリソースを管理するためのシェル環境である Cloud Shell を使用します。

Cloud Shell には、Google Cloud CLI と Ruby がプリインストールされています。gcloud CLI は、 Google Cloudの主要なコマンドライン インターフェースを提供します。

Cloud Shell を起動します。

  1. Google Cloud コンソールに移動します。

    Google Cloud コンソール

  2. Google Cloud コンソールのツールバーで、[Cloud Shell をアクティブにする] をクリックします。

コンソールの下部にあるフレーム内で Cloud Shell セッションが開きます。このシェルで gcloud コマンドを実行します。

認証を構成する

Ruby は、Artifact Registry リポジトリへのリクエストを認証する 2 つの方法をサポートしています。

  • RubyGems CLI: push リクエストと pull リクエストをサポートします。この CLI はデフォルトで Ruby で使用できます。RubyGems で認証する場合は、リポジトリに push リクエストまたは pull リクエストを行うたびに認証する必要があります。

  • Bundler CLI: pull リクエストをサポートします。Bundler は、パッケージとアップストリームを gemfile に保存します。これにより、ユーザーは個々の pull リクエストを認証することなく、複数のマシンで設定を標準化できます。ただし、Bundler に対して認証情報を再認証する必要がある場合があります。

    Bundler CLI をインストールするには、gem install bundler と入力します。

RubyGems CLI で認証する

RubyGems CLI は、OAuth2 トークンを使用してリクエストを認証します。Artifact Registry リポジトリへの呼び出しに OAuth2 トークンを渡すには、リクエストを行うときにリポジトリのアドレスとともに Oauth2 トークンを渡す必要があります。トークンの有効期間は 1 時間で、1 時間ごとに更新する必要があります。

pull リクエストを認証する

Google Cloud CLI コマンドラインでプルリクエストを認証するか、.gemrc ファイルを更新して認証できます。

コマンドラインで pull リクエストを認証する

プルリクエストの最新バージョンの 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

push リクエストを認証する

プッシュ リクエストを認証するには、Google Cloud CLI コマンドラインを使用するか、認証情報ファイルを更新します。

コマンドラインで push リクエストを認証する

プッシュ リクエストを認証するには、次のコマンドを実行します。

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 です。

認証情報ファイルで push リクエストを認証する

gem コマンドライン ツールは、~/.gem/credentials ファイルを使用して、gem の push と pull の API キーを保存します。プッシュ リクエストでソースに対して認証を行うように認証情報ファイルを構成する手順は次のとおりです。

  1. 認証情報ファイルを更新します。

    1. ~/.gem/credentials を開き、リポジトリの行を追加します。キーはリポジトリの URL で、値は 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 を push します。認証情報ファイルでキーをすでに定義しているため、GEM_HOST_API_KEY を設定する必要はありません。

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

Bundler で認証する

Ruby の Bundler は、1 つ以上の 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 という名前の gem が作成されました。次のセクションでは、RubyGems CLI を使用して gem をリポジトリに push します。

gem をリポジトリに push する

gem をリポジトリに push するには、次のコマンドを実行します。

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

ここで

  • GEM_NAME は、リポジトリに push する gem の名前です。
  • PROJECT は、プロジェクト ID です。このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。

リポジトリ内の gem を表示する

gem が追加されたことを確認するには、ruby-quickstart リポジトリ内のパッケージを一覧表示します。

次のコマンドを実行します。

gcloud artifacts packages list --repository=ruby-quickstart

gem のバージョンを表示するには、次のコマンドを実行します。

gcloud artifacts versions list --package=GEM_NAME

gem をインストールする

Artifact Registry リポジトリに push した gem をインストールするには、次のコマンドを実行します。

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

ここで

  • GEM_NAME は、リポジトリにインストールする gem の名前です。
  • PROJECT は、プロジェクト ID です。このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。

トラブルシューティング

詳細については、Ruby Gems のトラブルシューティングをご覧ください。

クリーンアップ

このページで使用したリソースについて、 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

次のステップ