Menyimpan gem Ruby di Artifact Registry

Panduan memulai ini menunjukkan cara menyiapkan repositori Ruby Artifact Registry pribadi, lalu mengupload paket, yang juga disebut gem, ke repositori tersebut.

Sebelum memulai

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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

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

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

  5. 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 email address for a Google Account.

    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.

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

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

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

  9. 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 email address for a Google Account.

    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.

Meluncurkan Cloud Shell

Dalam panduan memulai ini, Anda akan menggunakan Cloud Shell, yang merupakan lingkungan shell untuk mengelola resource yang dihosting diGoogle Cloud.

Cloud Shell telah diinstal lebih dulu dengan Google Cloud CLI dan Ruby. gcloud CLI menyediakan antarmuka command line utama untuk Google Cloud.

Meluncurkan Cloud Shell:

  1. Buka konsol Google Cloud .

    Google Cloud console

  2. Di toolbar konsol Google Cloud , klik Activate Cloud Shell.

Sesi Cloud Shell akan terbuka di dalam frame yang lebih rendah di konsol. Anda menggunakan shell ini untuk menjalankan perintah gcloud.

Mengonfigurasi autentikasi

Ruby mendukung dua metode untuk mengautentikasi permintaan ke repositori Artifact Registry Anda:

  • RubyGems CLI: Mendukung permintaan push dan pull. CLI ini tersedia dengan Ruby secara default. Saat melakukan autentikasi dengan RubyGems, Anda harus melakukan autentikasi setiap kali Anda membuat permintaan push atau pull ke repositori Anda.

  • CLI Bundler: Mendukung permintaan pull. Bundler menyimpan paket dan upstream di gemfile, yang memungkinkan pengguna menstandardisasi penyiapan di beberapa mesin tanpa perlu mengautentikasi setiap pull request. Namun, Anda tetap harus mengautentikasi ulang kredensial Anda ke Bundler dari waktu ke waktu.

    Untuk menginstal Bundler CLI, masukkan gem install bundler.

Melakukan autentikasi dengan RubyGems CLI

RubyGems CLI menggunakan token OAuth2 untuk mengautentikasi permintaan. Untuk meneruskan token OAuth2 ke panggilan ke repositori Artifact Registry, Anda harus terlebih dahulu membuat token lalu meneruskannya dengan alamat repositori saat Anda membuat permintaan. Masa berlaku token adalah satu jam dan harus diperbarui setiap jam.

Mengautentikasi permintaan pull

Anda dapat mengautentikasi pull request di command line Google Cloud CLI atau dengan memperbarui file .gemrc.

Mengautentikasi permintaan pull di command line

Untuk mengautentikasi versi terbaru gem di pull request Anda, jalankan perintah berikut:

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

Untuk mengautentikasi versi gem tertentu, tambahkan -v GEM_VERSION ke perintah gem install.

Dengan:

  • GEM_NAME adalah nama gem yang permintaannya dibuat.
  • LOCATION adalah lokasi regional atau multi-regional untuk repositori.
  • PROJECT adalah ID project yang berisi repositori.
  • REPOSITORY adalah ID repositori.

Mengautentikasi dalam file .gemrc

Anda dapat mengonfigurasi file /.gemrc global atau khusus project untuk mengautentikasi ke sumber Anda pada permintaan pull dengan menambahkan berikut ini:

# 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/
<...>

Untuk menginstal gem menggunakan sumber yang ditentukan dalam file /.gemrc, jalankan:

gem install GEM_NAME

Mengautentikasi permintaan push

Anda dapat mengautentikasi permintaan push di command line Google Cloud CLI atau dengan memperbarui file kredensial Anda.

Mengautentikasi permintaan push di command line

Untuk mengautentikasi permintaan push, jalankan perintah berikut:

export GEM_HOST_API_KEY="Bearer $(gcloud auth print-access-token)"
gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Dengan:

  • GEM_NAME adalah nama gem yang permintaannya dibuat.
  • LOCATION adalah lokasi regional atau multi-regional untuk repositori.
  • PROJECT adalah ID project yang berisi repositori.
  • REPOSITORY adalah ID repositori.

Mengautentikasi permintaan push dalam file kredensial

Alat command line gem menggunakan file ~/.gem/credentials untuk menyimpan kunci API guna mengirim dan menarik gem. Untuk mengonfigurasi file kredensial Anda agar mengautentikasi sumber Anda pada permintaan push, lakukan hal berikut:

  1. Buat token akses OAuth2 dengan menjalankan perintah berikut:

    gcloud auth print-access-token

    Token ini berfungsi sebagai kunci API Anda untuk Artifact Registry.

  2. Perbarui file kredensial Anda:

    1. Buka ~/.gem/credentials dan tambahkan baris untuk repositori Anda. Kuncinya adalah URL repositori Anda, dan nilainya adalah Bearer, diikuti dengan token Anda:

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

      Dengan:

      • RUBYGEMS_ORG_KEY adalah kunci API untuk RubyGems.org.
      • LOCATION adalah lokasi regional atau multi-regional untuk repositori.
      • PROJECT adalah ID project yang berisi repositori.
      • REPOSITORY adalah ID repositori.
      • OAUTH_TOKEN adalah token akses OAuth2 Anda.

    2. Dorong gem Anda. Perhatikan bahwa Anda tidak perlu menetapkan GEM_HOST_API_KEY, karena Anda telah menentukan kunci dalam file kredensial.

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

Melakukan autentikasi dengan Bundler

Bundler Ruby mengelola dependensi aplikasi di satu atau beberapa gem. Untuk menyiapkan Bundler, lakukan hal berikut:

  1. Tambahkan alamat repositori Anda sebagai source di gemfile Anda:

    # Gemfile
# <...>
source "https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"

  2. Lakukan autentikasi ke repositori Anda menggunakan 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

Dengan:

  • LOCATION adalah lokasi regional atau multi-regional untuk repositori.
  • PROJECT adalah project ID. Jika flag ini dihilangkan, project saat ini atau default akan digunakan.
  • REPOSITORY adalah ID repositori. Jika Anda mengonfigurasi repositori Artifact Registry default, repositori tersebut akan digunakan jika flag ini tidak disertakan dalam perintah.

Anda harus melakukan autentikasi ulang ke repositori jarak jauh Anda dari waktu ke waktu. Dalam peristiwa ini, jalankan perintah autentikasi yang sama dari Langkah 2.

Untuk mengetahui informasi selengkapnya tentang mengonfigurasi Bundler, lihat Gemfiles dalam dokumentasi bundler.io.

Untuk mengetahui informasi selengkapnya tentang metode autentikasi, lihat Mengonfigurasi autentikasi ke Artifact Registry untuk repositori gem Ruby.

Membuat repositori

Buat repositori untuk gem Anda.

  1. Jalankan perintah berikut untuk membuat repositori gem Ruby baru di project saat ini bernama quickstart-ruby-repo di lokasi us-west1.

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

  2. Jalankan perintah berikut untuk memverifikasi bahwa repositori Anda telah dibuat:

    gcloud artifacts repositories list

  3. Untuk menyederhanakan perintah gcloud, tetapkan repositori default ke quickstart-ruby-repo dan lokasi default ke us-west1. Setelah nilai ditetapkan, Anda tidak perlu menentukannya dalam perintah gcloud yang memerlukan repositori atau lokasi.

    Untuk menyetel repositori, jalankan perintah berikut:

    gcloud config set artifacts/repository quickstart-ruby-repo

    Untuk menyetel lokasi, jalankan perintah berikut:

    gcloud config set artifacts/location us-west1

    Untuk mengetahui informasi selengkapnya tentang perintah ini, lihat dokumentasi gcloud config set.

Mendownload gem

Saat Anda membangun project Ruby, file distribusi akan disimpan di subdirektori lib dalam project Ruby Anda. Untuk menyederhanakan panduan memulai ini, Anda akan membuat direktori, lalu mendownload gem ke direktori tersebut.

Untuk membuat direktori, jalankan perintah berikut:

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

Selanjutnya, download gem Anda. Anda dapat menggunakan gem Anda sendiri atau mendownload contoh gem dari halaman Gem Populer di rubygems.org. Untuk mendownload gem dari rubygems.org, jalankan perintah berikut:

gem fetch GEM_NAME

Sekarang Anda memiliki gem berjudul GEM_NAME di direktori ruby_quickstart/lib. Di bagian berikutnya, Anda akan menggunakan RubyGems CLI untuk mengirimkan gem ke repositori.

Kirim gem ke repositori

Untuk mengirim gem ke repositori Anda, jalankan perintah berikut:

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

Dengan:

  • GEM_NAME adalah nama gem yang akan di-push ke repositori Anda.
  • PROJECT adalah project ID. Jika flag ini tidak ada, maka project default saat ini atau akan digunakan.

Melihat gem di repositori

Untuk memverifikasi bahwa gem Anda telah ditambahkan, cantumkan paket di repositori ruby-quickstart.

Jalankan perintah berikut:

gcloud artifacts packages list --repository=ruby-quickstart

Untuk melihat versi gem, jalankan perintah berikut:

gcloud artifacts versions list --package=GEM_NAME

Instal gem

Untuk menginstal gem yang baru saja Anda kirim ke repositori Artifact Registry, jalankan perintah berikut:

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

Dengan:

  • GEM_NAME adalah nama gem yang akan diinstal di repositori Anda.
  • PROJECT adalah project ID. Jika flag ini tidak ada, maka project default saat ini atau akan digunakan.

Pemecahan masalah

Lihat Pemecahan masalah untuk gem Ruby untuk mengetahui informasi selengkapnya.

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut.

Sebelum menghapus repositori, pastikan gem apa pun yang ingin Anda simpan tersedia di lokasi lain.

  1. Untuk menghapus repositori quickstart-ruby-repo, jalankan perintah berikut:

    gcloud artifacts repositories delete quickstart-ruby-repo

  2. Jika Anda ingin menghapus setelan repositori dan lokasi default yang Anda konfigurasi untuk konfigurasi gcloud yang aktif, jalankan perintah berikut:

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

Langkah berikutnya