Archiviare i gem Ruby in Artifact Registry

Questa guida rapida mostra come configurare un repository Ruby privato di Artifact Registry e poi caricare un pacchetto, chiamato anche gem, in quel repository.

Prima di iniziare

  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.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire i repository di gem Ruby di Artifact Registry, chiedi all'amministratore di concederti il ruolo IAM Amministratore di Artifact Registry (roles/artifactregistry.admin) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Avvia Cloud Shell

In questa guida rapida utilizzerai Cloud Shell, un ambiente shell per la gestione delle risorse ospitate su Google Cloud.

Cloud Shell include Google Cloud CLI e Ruby preinstallati. gcloud CLI fornisce l'interfaccia a riga di comando principale per per Google Cloud.

Avvia Cloud Shell:

  1. Vai alla Google Cloud console.

    Google Cloud console

  2. Nella barra degli strumenti della Google Cloud console, fai clic su Attiva Cloud Shell.

Una sessione di Cloud Shell si apre in un frame nella parte inferiore della console. Utilizza questa shell per eseguire i comandi gcloud.

Configura l'autenticazione

Ruby supporta due metodi per autenticare le richieste al repository Artifact Registry:

  • RubyGems CLI: supporta le richieste di push e pull. Questa CLI è disponibile con Ruby per impostazione predefinita. Quando esegui l'autenticazione con RubyGems, devi autenticarti ogni volta che effettui una richiesta di push o pull al repository.

  • Bundler CLI: supporta le richieste di pull. Bundler archivia pacchetti e upstream in un gemfile, che consente agli utenti di standardizzare le configurazioni su più macchine senza dover autenticare ogni singola richiesta di pull. Tuttavia, di tanto in tanto devi comunque autenticare di nuovo le tue credenziali in Bundler.

    Per installare Bundler CLI, inserisci gem install bundler.

Esegui l'autenticazione con RubyGems CLI

RubyGems CLI utilizza i token OAuth2 per autenticare una richiesta. Per passare i token OAuth2 alle chiamate ai repository Artifact Registry, devi passare il token OAuth2 con l'indirizzo del repository quando effettui una richiesta. I token hanno una durata di un'ora e devono essere aggiornati ogni ora.

Autentica le richieste di pull

Puoi autenticare una richiesta di pull nella riga di comando di Google Cloud CLI o aggiornando il file .gemrc.

Autentica le richieste di pull nella riga di comando

Per eseguire l'autenticazione per l'ultima versione del gem nella richiesta di pull, esegui il comando seguente:

gem install GEM_NAME --source https://$ACCESS_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Per eseguire l'autenticazione per una versione specifica del gem, aggiungi -v GEM_VERSION al comando gem install.

Dove:

  • GEM_NAME è il nome del gem per cui viene effettuata la richiesta.
  • LOCATION è la località regionale o multi-regionale del repository.
  • PROJECT è l'ID del progetto contenente il repository.
  • REPOSITORY è l'ID del repository.

Esegui l'autenticazione in un file .gemrc

Puoi configurare il file /.gemrc globale o specifico del progetto per eseguire l'autenticazione alle origini nelle richieste di pull aggiungendo quanto segue:

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

Dove:

  • ACCESS_TOKEN è il tuo token di accesso OAuth2.
  • LOCATION è la località regionale o multi-regionale del repository.
  • PROJECT è l'ID del progetto contenente il repository.
  • REPOSITORY è l'ID del repository.

Per installare un gem utilizzando l'origine o le origini definite nel file /.gemrc, esegui:

gem install GEM_NAME

Autentica le richieste di push

Puoi autenticare una richiesta di push nella riga di comando di Google Cloud CLI o aggiornando il file delle credenziali.

Autentica le richieste di push nella riga di comando

Per autenticare la richiesta di push, esegui il comando seguente:

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

Dove:

  • GEM_NAME è il nome del gem per cui viene effettuata la richiesta.
  • LOCATION è la località regionale o multi-regionale del repository.
  • PROJECT è l'ID del progetto contenente il repository.
  • REPOSITORY è l'ID del repository.

Autentica le richieste di push in un file delle credenziali

Lo strumento a riga di comando gem utilizza il file ~/.gem/credentials per archiviare le chiavi API per il push e il pull dei gem. Per configurare il file delle credenziali per eseguire l'autenticazione alle origini nelle richieste di push:

  1. Aggiorna il file delle credenziali:

    1. Apri ~/.gem/credentials e aggiungi una riga per il repository. La chiave è l'URL del repository e il valore è Bearer, seguito dal token:

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

      Dove:

      • RUBYGEMS_ORG_KEY è la chiave API per RubyGems.org.
      • LOCATION è la località regionale o multi-regionale del repository.
      • PROJECT è l'ID del progetto contenente il repository.
      • REPOSITORY è l'ID del repository.
      • ACCESS_TOKEN è il tuo token di accesso OAuth2.

    2. Esegui il push del gem. Tieni presente che non devi impostare GEM_HOST_API_KEY, perché hai già definito la chiave nel file delle credenziali.

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

Esegui l'autenticazione con Bundler

Ruby Bundler gestisce le dipendenze delle applicazioni in uno o più gem. Per configurare Bundler:

  1. Aggiungi l'indirizzo del repository come source nel gemfile:

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

  2. Esegui l'autenticazione al repository utilizzando 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

Dove:

  • LOCATION è la località regionale o multi-regionale del repository.
  • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
  • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, questo viene utilizzato quando questo flag viene omesso dal comando.

Di tanto in tanto dovrai eseguire di nuovo l'autenticazione al repository remoto. In questo caso, esegui lo stesso comando di autenticazione del passaggio 2.

Per saperne di più sulla configurazione di Bundler, consulta Gemfiles nella documentazione di bundler.io.

Per saperne di più sui metodi di autenticazione, consulta Configurare l'autenticazione ad Artifact Registry per i repository di gem Ruby.

Crea un repository

Crea il repository per il gem.

  1. Esegui il comando seguente per creare un nuovo repository di gem Ruby nel progetto corrente denominato quickstart-ruby-repo nella località us-west1.

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

  2. Esegui questo comando per verificare che il repository sia stato creato:

    gcloud artifacts repositories list

  3. Per semplificare i comandi gcloud, imposta il repository predefinito su quickstart-ruby-repo e la località predefinita su us-west1. Una volta impostati i valori, non devi specificarli nei comandi gcloud che richiedono un repository o una località.

    Per impostare il repository, esegui il comando seguente:

    gcloud config set artifacts/repository quickstart-ruby-repo

    Per impostare la località, esegui il comando seguente:

    gcloud config set artifacts/location us-west1

    Per ulteriori informazioni su questi comandi, consulta la documentazione di gcloud config set.

Scarica un gem

Quando crei un progetto Ruby, i file di distribuzione vengono salvati in una sottodirectory lib nel progetto Ruby. Per semplificare questa guida rapida, creerai una directory e poi scaricherai un gem in quella directory.

Per creare la directory, esegui questo comando:

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

Poi scarica il gem. Puoi utilizzare il tuo gem o scaricare un gem di esempio dalla pagina Gem popolari su rubygems.org. Per scaricare un gem da rubygems.org, esegui questo comando:

gem fetch GEM_NAME

Ora hai un gem denominato GEM_NAME nella directory ruby_quickstart/lib. Nella sezione successiva, utilizzerai RubyGems CLI per eseguire il push del gem nel repository.

Esegui il push del gem nel repository

Per eseguire il push del gem nel repository, esegui questo comando:

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

Dove:

  • GEM_NAME è il nome del gem di cui eseguire il push nel repository.
  • PROJECT è l'ID progetto. Se questo flag viene omesso, allora il progetto corrente o predefinito viene utilizzato.

Visualizza il gem nel repository

Per verificare che il gem sia stato aggiunto, elenca i pacchetti nel repository ruby-quickstart.

Esegui questo comando:

gcloud artifacts packages list --repository=ruby-quickstart

Per visualizzare le versioni di un gem, esegui questo comando:

gcloud artifacts versions list --package=GEM_NAME

Installa il gem

Per installare il gem di cui hai appena eseguito il push nel repository Artifact Registry, esegui questo comando:

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

Dove:

  • GEM_NAME è il nome del gem da installare nel repository.
  • PROJECT è l'ID progetto. Se questo flag viene omesso, allora il progetto corrente o predefinito viene utilizzato.

Risoluzione dei problemi

Per saperne di più, consulta Risoluzione dei problemi relativi ai gem Ruby.

Esegui la pulizia

Per evitare che al tuo Google Cloud account vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi.

Prima di rimuovere il repository, assicurati che tutti i gem che vuoi conservare siano disponibili in un'altra posizione.

  1. Per eliminare il repository quickstart-ruby-repo, esegui questo comando:

    gcloud artifacts repositories delete quickstart-ruby-repo

  2. Se vuoi rimuovere il repository predefinito e le impostazioni di posizione configurate per la configurazione gcloud attiva, esegui i comandi seguenti:

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

Passaggi successivi