Archiviare gem Ruby in Artifact Registry

Archiviare gem Ruby in Artifact Registry

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

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

Prima di iniziare

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.

   Vai a IAM
2. Seleziona il progetto.
3. Fai clic su Concedi l'accesso.

4. Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'indirizzo email di un Account Google.

5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
7. Fai clic su Salva.

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.

   Vai a IAM
2. Seleziona il progetto.
3. Fai clic su Concedi l'accesso.

4. Nel campo Nuove entità, inserisci il tuo identificatore dell'utente. In genere si tratta dell'indirizzo email di un Account Google.

5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo successivo.
7. Fai clic su Salva.

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

Avvia Cloud Shell:

1. Vai alla console Google Cloud .

   Google Cloud console

2. Nella barra degli strumenti della console Google Cloud , 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:

• Interfaccia a riga di comando RubyGems: supporta le richieste 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 push o pull al tuo repository.

• Interfaccia a riga di comando Bundler: supporta le richieste di pull. Bundler memorizza pacchetti e upstream in un gemfile, che consente agli utenti di standardizzare le configurazioni su più macchine senza dover autenticare ogni singola richiesta pull. Tuttavia, di tanto in tanto devi comunque eseguire nuovamente l'autenticazione delle credenziali in Bundler.

  Per installare Bundler CLI, inserisci gem install bundler.

Esegui l'autenticazione con RubyGems CLI

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

Autenticare le richieste di pull

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

Autenticare le richieste pull nella riga di comando

Per eseguire l'autenticazione per l'ultima versione della gemma nella richiesta pull, esegui questo comando:

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

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

Dove:

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

Autenticarsi in un file .gemrc

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

# File: ~/.gemrc

# Use the GEM_TOKEN retrieved from export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://[e-mail]/PROJECT/REPO/
<...>

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

gem install GEM_NAME

Autenticare le richieste push

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

Autenticare le richieste push nella riga di comando

Per autenticare la richiesta di push, esegui questo comando:

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

Nota: dopo aver definito GEM_HOST_API_KEY, le richieste push non devono trasmettere il token OAuth2 nell'URL.

Dove:

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

Autenticare le richieste 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 di gem. Per configurare il file delle credenziali per l'autenticazione alle origini nelle richieste push:

1. Genera un token di accesso OAuth2 eseguendo il seguente comando:

   gcloud auth print-access-token

   Questo token funge da chiave API per Artifact Registry.

2. Aggiorna il file delle credenziali:

   1. Apri ~/.gem/credentials e aggiungi una riga per il tuo 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 OAUTH_TOKEN
      

      Dove:

      • RUBYGEMS_ORG_KEY è la chiave API per RubyGems.org.
      • LOCATION è la posizione regionale o multiregionale del repository.
      • PROJECT è l'ID del progetto contenente il repository.
      • REPOSITORY è l'ID del repository.
      • OAUTH_TOKEN è il tuo token di accesso OAuth2.

   2. Esegui il push del tuo Gem. Tieni presente che non devi impostare GEM_HOST_API_KEY, in quanto hai già definito la chiave nel file delle credenziali.

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

Autenticarsi con Bundler

Bundler di Ruby gestisce le dipendenze delle applicazioni in una o più gemme. Per configurare Bundler:

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

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

2. Esegui l'autenticazione nel 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 posizione regionale o multiregionale del repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto predefinito corrente.
• 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 nuovamente l'autenticazione al repository remoto. In questo caso, esegui lo stesso comando di autenticazione del passaggio 2.

Per ulteriori informazioni sulla configurazione di Bundler, consulta la sezione Gemfiles nella documentazione di bundler.io.

Per saperne di più sui metodi di autenticazione, vedi Configura l'autenticazione in Artifact Registry per i repository di gem Ruby.

Crea un repository

Crea il repository per la tua gemma.

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 posizione predefinita su us-west1. Una volta impostati i valori, non è necessario specificarli nei comandi gcloud che richiedono un repository o una posizione.

   Per impostare il repository, esegui questo comando:

   gcloud config set artifacts/repository quickstart-ruby-repo
   

   Per impostare la località, esegui questo comando:

   gcloud config set artifacts/location us-west1
   

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

Scaricare un gem

Quando crei un progetto Ruby, i file di distribuzione vengono salvati in una sottodirectory lib del 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 tuo gem. Puoi utilizzare il tuo Gem o scaricarne uno di esempio dalla pagina Gem più usati su rubygems.org. Per scaricare un gem da rubygems.org, esegui questo comando:

gem fetch GEM_NAME

Ora hai un gem chiamato GEM_NAME nella directory ruby_quickstart/lib. Nella sezione successiva utilizzerai RubyGems CLI per eseguire il push della gemma nel repository.

Esegui il push della gemma nel repository

Per eseguire il push della gemma 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 da eseguire il push nel repository.
• PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.

Visualizzare la gemma 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 una gemma, esegui questo comando:

gcloud artifacts versions list --package=GEM_NAME

Installare il gem

Per installare la gemma appena inviata al repository Artifact Registry, esegui questo comando:

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

Dove:

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

Risoluzione dei problemi

Per saperne di più, consulta la sezione Risoluzione dei problemi relativi ai pacchetti Ruby.

Esegui la pulizia

Per evitare che al tuo account Google Cloud 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

• Scopri di più sulla configurazione dell'autenticazione
• Scopri di più sulla gestione dei repository
• Scopri di più sulla gestione dei pacchetti
• Leggi le nostre risorse su DevOps ed esplora il nostro programma di ricerca.