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

  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.

      Buka IAM
    2. Pilih project.
    3. Klik Grant access.

    4. Di kolom New principals, masukkan ID pengguna Anda. Biasanya berupa alamat email untuk Akun Google.

    5. Di daftar Select a role, pilih peran.
    6. Untuk memberikan peran tambahan, klik Add another role, lalu tambahkan setiap peran tambahan.
    7. Klik Simpan.

  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.

      Buka IAM
    2. Pilih project.
    3. Klik Grant access.

    4. Di kolom New principals, masukkan ID pengguna Anda. Biasanya berupa alamat email untuk Akun Google.

    5. Di daftar Select a role, pilih peran.
    6. Untuk memberikan peran tambahan, klik Add another role, lalu tambahkan setiap peran tambahan.
    7. Klik Simpan.

    10. 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 melakukan autentikasi ulang kredensial ke Bundler sesekali.

      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 gem terbaru 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 pull request 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 aktif, jalankan perintah berikut:

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

    Langkah berikutnya