Stocker des gems Ruby dans Artifact Registry

Stocker des gems Ruby dans Artifact Registry

Preview

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce guide de démarrage rapide vous explique comment configurer un dépôt Ruby Artifact Registry privé, puis y importer un package, également appelé gem.

Avant de commencer

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.

   Accéder à IAM
2. Sélectionnez le projet.
3. Cliquez sur  Accorder l'accès.

4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail d'un compte Google.

5. Dans la liste Sélectionner un rôle, sélectionnez un rôle.
6. Pour attribuer des rôles supplémentaires, cliquez sur  Ajouter un autre rôle et ajoutez tous les rôles supplémentaires.
7. Cliquez sur Enregistrer.

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.

   Accéder à IAM
2. Sélectionnez le projet.
3. Cliquez sur  Accorder l'accès.

4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail d'un compte Google.

5. Dans la liste Sélectionner un rôle, sélectionnez un rôle.
6. Pour attribuer des rôles supplémentaires, cliquez sur  Ajouter un autre rôle et ajoutez tous les rôles supplémentaires.
7. Cliquez sur Enregistrer.

Lancer Cloud Shell

Dans ce guide de démarrage rapide, vous allez utiliser Cloud Shell, un environnement shell permettant de gérer les ressources hébergées surGoogle Cloud.

Cloud Shell est préinstallé avec Google Cloud CLI et Ruby. gcloud CLI fournit l'interface de ligne de commande principale pour Google Cloud.

Lancez Cloud Shell :

1. Accédez à la console Google Cloud .

   ConsoleGoogle Cloud

2. Dans la barre d'outils de la console Google Cloud , cliquez sur Activer Cloud Shell.

Une session Cloud Shell s'ouvre dans un cadre situé en bas de la console. Cette interface système vous permet d'exécuter les commandes gcloud.

Configurer l'authentification

Ruby est compatible avec deux méthodes d'authentification des requêtes envoyées à votre dépôt Artifact Registry :

• CLI RubyGems : compatible avec les requêtes push et pull. Cette CLI est disponible avec Ruby par défaut. Lorsque vous vous authentifiez auprès de RubyGems, vous devez vous authentifier chaque fois que vous effectuez une requête push ou pull vers votre dépôt.

• CLI Bundler : compatible avec les demandes d'extraction. Bundler stocke les packages et les flux en amont dans un fichier Gemfile, ce qui permet aux utilisateurs de standardiser les configurations sur plusieurs machines sans avoir à authentifier chaque demande d'extraction individuelle. Toutefois, vous devez toujours réauthentifier vos identifiants auprès de Bundler de temps en temps.

  Pour installer la CLI Bundler, saisissez gem install bundler.

S'authentifier avec RubyGems CLI

L'interface de ligne de commande RubyGems utilise des jetons OAuth2 pour authentifier une requête. Pour transmettre des jetons OAuth2 aux appels à vos dépôts Artifact Registry, vous devez d'abord générer le jeton, puis le transmettre avec l'adresse de votre dépôt lorsque vous effectuez une requête. Les jetons ont une durée de vie d'une heure et doivent être actualisés toutes les heures.

Authentifier les demandes d'extraction

Vous pouvez authentifier une demande d'extraction dans la ligne de commande Google Cloud CLI ou en mettant à jour votre fichier .gemrc.

Authentifier les demandes d'extraction dans la ligne de commande

Pour vous authentifier pour la dernière version du gem dans votre demande d'extraction;extraction, exécutez la commande suivante :

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

Pour vous authentifier pour une version spécifique de gem, ajoutez -v GEM_VERSION à la commande gem install.

Où :

• GEM_NAME est le nom du gem pour lequel la demande est effectuée.
• LOCATION est l'emplacement régional ou multirégional du dépôt.
• PROJECT est l'ID du projet contenant le dépôt.
• REPOSITORY est l'ID du dépôt.

S'authentifier dans un fichier .gemrc

Vous pouvez configurer votre fichier /.gemrc global ou spécifique à un projet pour vous authentifier auprès de vos sources sur les demandes d'extraction en ajoutant les éléments suivants :

# File: ~/.gemrc

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

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

Pour installer un gem à l'aide de la ou des sources définies dans votre fichier /.gemrc, exécutez la commande suivante :

gem install GEM_NAME

Authentifier les requêtes push

Vous pouvez authentifier une requête push dans la ligne de commande Google Cloud CLI ou en mettant à jour votre fichier d'identifiants.

Authentifier les requêtes push dans la ligne de commande

Pour authentifier votre requête push, exécutez la commande suivante :

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

Remarque : Une fois que GEM_HOST_API_KEY a été défini, les requêtes push n'ont plus besoin de transmettre le jeton OAuth2 dans l'URL.

Où :

• GEM_NAME est le nom du gem pour lequel la demande est effectuée.
• LOCATION est l'emplacement régional ou multirégional du dépôt.
• PROJECT est l'ID du projet contenant le dépôt.
• REPOSITORY est l'ID du dépôt.

Authentifier les requêtes push dans un fichier d'identifiants

L'outil de ligne de commande gem utilise le fichier ~/.gem/credentials pour stocker les clés API permettant d'envoyer et d'extraire des gems. Pour configurer votre fichier d'identifiants afin de vous authentifier auprès de vos sources sur les requêtes push, procédez comme suit :

1. Générez un jeton d'accès OAuth2 en exécutant la commande suivante :

   gcloud auth print-access-token

   Ce jeton sert de clé API pour Artifact Registry.

2. Mettez à jour votre fichier d'identifiants :

   1. Ouvrez ~/.gem/credentials et ajoutez une ligne pour votre dépôt. La clé correspond à l'URL de votre dépôt, et la valeur est Bearer, suivie de votre jeton :

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

      Où :

      • RUBYGEMS_ORG_KEY est la clé API pour RubyGems.org.
      • LOCATION est l'emplacement régional ou multirégional du dépôt.
      • PROJECT est l'ID du projet contenant le dépôt.
      • REPOSITORY est l'ID du dépôt.
      • OAUTH_TOKEN est votre jeton d'accès OAuth2.

   2. Transmettez votre gem. Notez que vous n'avez pas besoin de définir GEM_HOST_API_KEY, car vous avez déjà défini la clé dans votre fichier d'identifiants.

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

S'authentifier avec Bundler

Le Bundler Ruby gère les dépendances des applications sur un ou plusieurs gems. Pour configurer Bundler, procédez comme suit :

1. Ajoutez l'adresse de votre dépôt en tant que source dans votre fichier Gemfile :

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

2. Authentifiez-vous auprès de votre dépôt à l'aide de 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
   

Où :

• LOCATION est l'emplacement régional ou multirégional du dépôt.
• PROJECT est l'ID de projet. Si cette option est ignorée, le projet en cours ou par défaut est utilisé.
• REPOSITORY est l'ID du dépôt. Si vous avez configuré un dépôt Artifact Registry par défaut, il est utilisé lorsque cette option est omise dans la commande.

Vous devrez parfois vous réauthentifier auprès de votre dépôt distant. Dans ce cas, exécutez la même commande d'authentification que celle de l'étape 2.

Pour en savoir plus sur la configuration de Bundler, consultez Gemfiles dans la documentation bundler.io.

Pour en savoir plus sur les méthodes d'authentification, consultez Configurer l'authentification pour Artifact Registry pour les dépôts de gems Ruby.

Créer un dépôt

Créez le dépôt pour votre gem.

1. Exécutez la commande suivante pour créer un dépôt de gems Ruby dans le projet actuel nommé quickstart-ruby-repo à l'emplacement us-west1.

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

2. Exécutez la commande suivante pour vérifier que votre dépôt a bien été créé :

   gcloud artifacts repositories list
   

3. Pour simplifier les commandes gcloud, définissez le dépôt par défaut sur quickstart-ruby-repo et l'emplacement par défaut sur us-west1. Une fois les valeurs définies, vous n'avez pas besoin de les spécifier dans les commandes gcloud nécessitant un dépôt ou un emplacement.

   Pour définir le dépôt, exécutez la commande suivante :

   gcloud config set artifacts/repository quickstart-ruby-repo
   

   Pour définir l'emplacement, exécutez la commande suivante :

   gcloud config set artifacts/location us-west1
   

   Pour plus d'informations sur ces commandes, consultez la documentation gcloud config set.

Télécharger un gem

Lorsque vous compilez un projet Ruby, les fichiers de distribution sont enregistrés dans un sous-répertoire lib de votre projet Ruby. Pour simplifier ce guide de démarrage rapide, vous allez créer un répertoire, puis y télécharger un gem.

Pour créer le répertoire, exécutez la commande suivante :

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

Ensuite, téléchargez votre gem. Vous pouvez utiliser votre propre Gem ou télécharger un exemple de Gem depuis la page Gems populaires sur rubygems.org. Pour télécharger un gem depuis rubygems.org, exécutez la commande suivante :

gem fetch GEM_NAME

Vous disposez maintenant d'un gem nommé GEM_NAME dans votre répertoire ruby_quickstart/lib. Dans la section suivante, vous utiliserez la CLI RubyGems pour envoyer votre gem à votre dépôt.

Transférer le gem vers le dépôt

Pour transférer le gem vers votre dépôt, exécutez la commande suivante :

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

Où :

• GEM_NAME est le nom du gem à envoyer à votre dépôt.
• PROJECT est l'ID de projet. Si cette option est ignorée, le projet en cours ou par défaut est utilisé.

Afficher le gem dans le dépôt

Pour vérifier que votre gem a bien été ajouté, listez les packages dans le dépôt ruby-quickstart.

Exécutez la commande suivante :

gcloud artifacts packages list --repository=ruby-quickstart

Pour afficher les versions d'un gem, exécutez la commande suivante :

gcloud artifacts versions list --package=GEM_NAME

Installer le gem

Pour installer le gem que vous venez de transférer vers votre dépôt Artifact Registry, exécutez la commande suivante :

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

Où :

• GEM_NAME est le nom du gem à installer dans votre dépôt.
• PROJECT est l'ID de projet. Si cette option est ignorée, le projet en cours ou par défaut est utilisé.

Dépannage

Pour en savoir plus, consultez Dépannage des gems Ruby.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cette démonstration soient facturées sur votre compte Google Cloud , procédez comme suit :

Avant de supprimer le dépôt, assurez-vous que tous les gems que vous souhaitez conserver sont disponibles à un autre emplacement.

1. Pour supprimer le dépôt quickstart-ruby-repo, exécutez la commande suivante :

   gcloud artifacts repositories delete quickstart-ruby-repo
   

2. Si vous souhaitez supprimer le dépôt par défaut et les paramètres d'emplacement que vous avez définis pour la configuration gcloud active, exécutez les commandes suivantes :

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

Étapes suivantes

• En savoir plus sur la configuration de l'authentification
• En savoir plus sur la gestion des dépôts
• En savoir plus sur la gestion des packages
• Consultez nos ressources sur le DevOps et découvrez notre programme de recherche.