Stocker des gems Ruby dans Artifact Registry

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

  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.

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des dépôts de gems Ruby Artifact Registry, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Artifact Registry (roles/artifactregistry.admin) dans votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

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

Cloud Shell est préinstallé avec le 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 Google Cloud console.

    Google Cloud Console

  2. Dans la barre d'outils de la Google Cloud console, 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 dans votre dépôt Artifact Registry :

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

  • CLI Bundler : compatible avec les requêtes pull. 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 la CLI RubyGems

La CLI RubyGems utilise des jetons OAuth2 pour authentifier une requête. Pour transmettre des jetons OAuth2 aux appels de vos dépôts Artifact Registry, vous devez transmettre votre jeton OAuth2 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 requêtes pull

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

Authentifier les requêtes pull dans la ligne de commande

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

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

Pour vous authentifier auprès d'une version spécifique du gem, ajoutez -v GEM_VERSION à la gem install commande.

Où :

  • GEM_NAME est le nom du gem pour lequel la requête est effectuée.
  • LOCATION est l'emplacement régional ou multirégional location 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 lors des requêtes pull en ajoutant les éléments suivants :

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

Où :

  • ACCESS_TOKEN est votre jeton d'accès OAuth2.
  • LOCATION est l'emplacement régional ou multirégional location du dépôt.
  • PROJECT est l'ID du projet contenant le dépôt.
  • REPOSITORY est l'ID du dépôt.

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

Où :

  • GEM_NAME est le nom du gem pour lequel la requête est effectuée.
  • LOCATION est l'emplacement régional ou multirégional location 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 lors des requêtes push, procédez comme suit :

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

      Où :

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

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

Ruby Bundler 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 location 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 vous réauthentifier auprès de votre dépôt distant de temps en temps. 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 la section Gemfiles de la documentation bundler.io.

Pour en savoir plus sur les méthodes d'authentification, consultez Configurer l'authentification auprès d'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 créez 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 à partir de la page Popular Gems (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 intitulé GEM_NAME dans votre ruby_quickstart/lib répertoire. Dans la section suivante, vous allez utiliser la CLI RubyGems pour envoyer votre gem à votre dépôt.

Envoyer le gem au dépôt

Pour envoyer le gem à 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, alors 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 d'envoyer à 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://$GEM_TOKEN@us-west1-ruby.pkg.dev/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, alors le projet en cours ou par défaut est utilisé.

Dépannage

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

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cette démonstration soient facturées sur votre Google Cloud compte pour les ressources utilisées sur cette page, 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

Étape suivante