Almacenar gemas de Ruby en Artifact Registry

Almacenar gemas de Ruby en Artifact Registry

Vista previa

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En esta guía de inicio rápido se muestra cómo configurar un repositorio privado de Ruby en Artifact Registry y, a continuación, subir un paquete, también llamado gem, a ese repositorio.

Antes de empezar

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.

   Ir a IAM
2. Selecciona el proyecto.
3. Haz clic en Conceder acceso.

4. En el campo Nuevos principales, introduce tu identificador de usuario. Normalmente, se trata de la dirección de correo de una cuenta de Google.

5. En la lista Selecciona un rol, elige un rol.
6. Para conceder más roles, haz clic en Añadir otro rol y añade cada rol adicional.
7. Haz clic en Guardar.

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.

   Ir a IAM
2. Selecciona el proyecto.
3. Haz clic en Conceder acceso.

4. En el campo Nuevos principales, introduce tu identificador de usuario. Normalmente, se trata de la dirección de correo de una cuenta de Google.

5. En la lista Selecciona un rol, elige un rol.
6. Para conceder más roles, haz clic en Añadir otro rol y añade cada rol adicional.
7. Haz clic en Guardar.

Abrir Cloud Shell

En esta guía de inicio rápido, usarás Cloud Shell, un entorno de shell para gestionar recursos alojados enGoogle Cloud.

Cloud Shell tiene preinstalado Google Cloud CLI y Ruby. La CLI de gcloud proporciona la interfaz de línea de comandos principal de Google Cloud.

Abre Cloud Shell:

1. Ve a la Google Cloud consola.

   Google Cloud console

2. En la barra de herramientas de la consola Google Cloud , haz clic en Activar Cloud Shell.

Se abrirá una sesión de Cloud Shell en un marco de la parte inferior de la consola. Esta shell se usa para ejecutar comandos gcloud.

Configurar la autenticación

Ruby admite dos métodos para autenticar solicitudes en tu repositorio de Artifact Registry:

• CLI de RubyGems: admite solicitudes de inserción y extracción. Esta CLI está disponible de forma predeterminada con Ruby. Cuando te autentiques con RubyGems, tendrás que autenticarte cada vez que hagas una solicitud push o pull a tu repositorio.

• CLI de Bundler: admite solicitudes de extracción. Bundler almacena paquetes y fuentes ascendentes en un archivo Gemfile, lo que permite a los usuarios estandarizar las configuraciones en varias máquinas sin necesidad de autenticar cada solicitud de extracción. Sin embargo, debes volver a autenticar tus credenciales en Bundler de vez en cuando.

  Para instalar la CLI de Bundler, introduce gem install bundler.

Autenticarse con la CLI de RubyGems

La CLI de RubyGems usa tokens de OAuth 2 para autenticar una solicitud. Para transferir tokens de OAuth2 a las llamadas a tus repositorios de Artifact Registry, primero debes generar el token y, a continuación, transferirlo junto con la dirección de tu repositorio cuando hagas una solicitud. Los tokens tienen una duración de una hora y deben actualizarse cada hora.

Autenticar solicitudes de extracción

Puedes autenticar una solicitud de extracción en la línea de comandos de la CLI de Google Cloud o actualizando el archivo .gemrc.

Autenticar solicitudes de extracción en la línea de comandos

Para autenticar la última versión de la gema en tu solicitud de extracción, ejecuta el siguiente comando:

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

Para autenticar una versión específica de una gema, añade -v GEM_VERSION al comando gem install.

Donde:

• GEM_NAME es el nombre del gem para el que se hace la solicitud.
• LOCATION es la ubicación regional o multirregional del repositorio.
• PROJECT es el ID del proyecto que contiene el repositorio.
• REPOSITORY es el ID del repositorio.

Autenticarse en un archivo .gemrc

Puedes configurar tu archivo /.gemrc global o específico del proyecto para autenticarte en tus fuentes en las solicitudes de extracción añadiendo lo siguiente:

# File: ~/.gemrc

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

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

Para instalar un gem usando la fuente o las fuentes definidas en el archivo /.gemrc, ejecuta el siguiente comando:

gem install GEM_NAME

Autenticar solicitudes de inserción

Puedes autenticar una solicitud push en la línea de comandos de la CLI de Google Cloud o actualizando tu archivo de credenciales.

Autenticar solicitudes push en la línea de comandos

Para autenticar tu solicitud push, ejecuta el siguiente 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: Una vez que se ha definido GEM_HOST_API_KEY, las solicitudes push no necesitan transferir el token de OAuth2 en la URL.

Donde:

• GEM_NAME es el nombre del gem para el que se hace la solicitud.
• LOCATION es la ubicación regional o multirregional del repositorio.
• PROJECT es el ID del proyecto que contiene el repositorio.
• REPOSITORY es el ID del repositorio.

Autenticar solicitudes de inserción en un archivo de credenciales

La herramienta de línea de comandos gem usa el archivo ~/.gem/credentials para almacenar las claves de API para enviar y extraer gemas. Para configurar el archivo de credenciales para autenticarte en tus fuentes en las solicitudes push, haz lo siguiente:

1. Genera un token de acceso de OAuth 2.0 ejecutando el siguiente comando:

   gcloud auth print-access-token

   Este token actúa como tu clave de API para Artifact Registry.

2. Actualiza el archivo de credenciales:

   1. Abre ~/.gem/credentials y añade una línea para tu repositorio. La clave es la URL de tu repositorio y el valor es Bearer, seguido de tu token:

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

      Donde:

      • RUBYGEMS_ORG_KEY es la clave de API de RubyGems.org.
      • LOCATION es la ubicación regional o multirregional del repositorio.
      • PROJECT es el ID del proyecto que contiene el repositorio.
      • REPOSITORY es el ID del repositorio.
      • OAUTH_TOKEN es tu token de acceso de OAuth 2.0.

   2. Empuja tu gema. Ten en cuenta que no es necesario que definas GEM_HOST_API_KEY, ya que has definido la clave en el archivo de credenciales.

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

Autenticarse con Bundler

Bundler de Ruby gestiona las dependencias de las aplicaciones en una o varias gemas. Para configurar Bundler, sigue estos pasos:

1. Añade la dirección de tu repositorio como source en tu archivo gemfile:

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

2. Autentícate en tu repositorio con 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
   

Donde:

• LOCATION es la ubicación regional o multirregional del repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado o el actual.
• REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.

De vez en cuando, tendrás que volver a autenticarte en tu repositorio remoto. En este caso, ejecuta el mismo comando de autenticación del paso 2.

Para obtener más información sobre cómo configurar Bundler, consulta Gemfiles en la documentación de bundler.io.

Para obtener más información sobre los métodos de autenticación, consulta Configurar la autenticación en Artifact Registry para repositorios de gemas de Ruby.

Crear un repositorio

Crea el repositorio de tu gem.

1. Ejecuta el siguiente comando para crear un nuevo repositorio de gemas de Ruby en el proyecto actual llamado quickstart-ruby-repo en la ubicación us-west1.

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

2. Ejecuta el siguiente comando para verificar que se ha creado el repositorio:

   gcloud artifacts repositories list
   

3. Para simplificar los comandos de gcloud, define el repositorio predeterminado como quickstart-ruby-repo y la ubicación predeterminada como us-west1. Una vez que se hayan definido los valores, no será necesario especificarlos en los comandos de gcloud que requieran un repositorio o una ubicación.

   Para definir el repositorio, ejecuta el siguiente comando:

   gcloud config set artifacts/repository quickstart-ruby-repo
   

   Para definir la ubicación, ejecuta el siguiente comando:

   gcloud config set artifacts/location us-west1
   

   Para obtener más información sobre estos comandos, consulta la documentación de gcloud config set.

Descargar un gem

Cuando compilas un proyecto de Ruby, los archivos de distribución se guardan en un subdirectorio lib de tu proyecto de Ruby. Para simplificar esta guía de inicio rápido, crearás un directorio y, a continuación, descargarás una gema en ese directorio.

Para crear el directorio, ejecuta el siguiente comando:

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

A continuación, descarga tu gem. Puedes usar tu propio Gem o descargar un Gem de ejemplo de la página Gems populares en rubygems.org. Para descargar una gema de rubygems.org, ejecuta el siguiente comando:

gem fetch GEM_NAME

Ahora tienes una gema llamada GEM_NAME en el directorio ruby_quickstart/lib. En la siguiente sección, usarás la CLI de RubyGems para enviar tu gem a tu repositorio.

Enviar la gema al repositorio

Para enviar la gema a tu repositorio, ejecuta el siguiente comando:

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

Donde:

• GEM_NAME es el nombre del gem que se insertará en tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado o el actual.

Ver la gema en el repositorio

Para verificar que se ha añadido tu gem, enumera los paquetes del repositorio ruby-quickstart.

Ejecuta el siguiente comando:

gcloud artifacts packages list --repository=ruby-quickstart

Para ver las versiones de una gema, ejecuta el siguiente comando:

gcloud artifacts versions list --package=GEM_NAME

Instala la gema

Para instalar la gema que acabas de enviar a tu repositorio de Artifact Registry, ejecuta el siguiente comando:

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

Donde:

• GEM_NAME es el nombre del gem que se va a instalar en tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado o el actual.

Solución de problemas

Consulta Solución de problemas de gemas de Ruby para obtener más información.

Limpieza

Para evitar que se apliquen cargos en tu cuenta de Google Cloud por los recursos utilizados en esta página, sigue estos pasos.

Antes de quitar el repositorio, asegúrate de que las gemas que quieras conservar estén disponibles en otra ubicación.

1. Para eliminar el repositorio quickstart-ruby-repo, ejecuta el siguiente comando:

   gcloud artifacts repositories delete quickstart-ruby-repo
   

2. Si quieres quitar los ajustes predeterminados de repositorio y ubicación que has configurado para la configuración gcloud activa, ejecuta los siguientes comandos:

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

Siguientes pasos

• Más información sobre cómo configurar la autenticación
• Más información sobre cómo gestionar repositorios
• Información sobre cómo gestionar paquetes
• Consulta nuestros recursos sobre DevOps y descubre nuestro programa de investigación.