Almacena gemas de Ruby en Artifact Registry

Almacena gemas de Ruby en Artifact Registry

Versión preliminar

Este producto o función está sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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

Antes de comenzar

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 Otorgar acceso.

4. En el campo Principales nuevas, ingresa tu identificador de usuario. Esta suele ser la dirección de correo electrónico de una Cuenta de Google.

5. En la lista Seleccionar un rol, elige uno.
6. Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega uno más.
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 Otorgar acceso.

4. En el campo Principales nuevas, ingresa tu identificador de usuario. Esta suele ser la dirección de correo electrónico de una Cuenta de Google.

5. En la lista Seleccionar un rol, elige uno.
6. Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega uno más.
7. Haz clic en Guardar.

Inicia Cloud Shell

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

Cloud Shell ya viene instalado en Google Cloud CLI y Ruby. Gcloud CLI proporciona la interfaz de línea de comandos principal para Google Cloud.

Iniciar Cloud Shell:

1. Ve a la consola de Google Cloud .

   Google Cloud console

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

Se abrirá una sesión de Cloud Shell dentro de un marco en la parte inferior en la consola. Usa esta shell para ejecutar los comandos de gcloud.

Configura la autenticación

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

• CLI de RubyGems: Admite solicitudes de extracción y envío. Esta CLI está disponible con Ruby de forma predeterminada. Cuando te autenticas con RubyGems, debes hacerlo cada vez que realices una solicitud de extracción o envío a tu repositorio.

• CLI de Bundler: Admite solicitudes de extracción. Bundler almacena paquetes y transmisiones ascendentes en un archivo gemfile, lo que permite a los usuarios estandarizar la configuración en varias máquinas sin necesidad de autenticar cada solicitud de extracción individual. Sin embargo, de vez en cuando, debes volver a autenticar tus credenciales en Bundler.

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

Autentícate con la CLI de RubyGems

La CLI de RubyGems usa tokens de OAuth2 para autenticar una solicitud. Para pasar tokens de OAuth2 a las llamadas a tus repositorios de Artifact Registry, primero debes generar el token y, luego, pasarlo con la dirección de tu repositorio cuando realices una solicitud. Los tokens tienen una vida útil de una hora y se deben actualizar cada hora.

Autentica solicitudes de extracción

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

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

Para autenticarte en la versión más reciente de la gem 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 la gem, agrega -v GEM_VERSION al comando gem install.

Aquí:

• GEM_NAME es el nombre de la gem para la que se realiza 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.

Autentícate 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 agregando 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 una gem con la fuente o las fuentes definidas en tu archivo /.gemrc, ejecuta el siguiente comando:

gem install GEM_NAME

Autentica solicitudes push

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

Autentica solicitudes push en la línea de comandos

Para autenticar tu solicitud de envío, 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: Después de definir GEM_HOST_API_KEY, las solicitudes push no necesitan pasar el token de OAuth2 en la URL.

Aquí:

• GEM_NAME es el nombre de la gem para la que se realiza 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.

Autentica solicitudes push en un archivo de credenciales

La herramienta de línea de comandos de gem usa el archivo ~/.gem/credentials para almacenar las claves de API para enviar y extraer gems. Para configurar tu archivo de credenciales de modo que se autentique en tus fuentes en las solicitudes de envío, haz lo siguiente:

1. Ejecuta el siguiente comando para generar un token de acceso de OAuth2:

   gcloud auth print-access-token

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

2. Actualiza tu archivo de credenciales:

   1. Abre ~/.gem/credentials y agrega 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
      

      Aquí:

      • RUBYGEMS_ORG_KEY es la clave de API para 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 OAuth2.

   2. Empuja tu Gem. Ten en cuenta que no es necesario que establezcas GEM_HOST_API_KEY, ya que definiste la clave en tu archivo de credenciales.

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

Autenticación con Bundler

El Bundler de Ruby administra las dependencias de la aplicación en una o más gemas. Para configurar Bundler, haz lo siguiente:

1. Agrega la dirección de tu repositorio como un source en tu 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
   

Aquí:

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

Deberás volver a autenticarte en tu repositorio remoto de vez en cuando. 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 Configura la autenticación en Artifact Registry para repositorios de gemas de Ruby.

Crea un repositorio

Crea el repositorio para 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 haya creado el repositorio:

   gcloud artifacts repositories list
   

3. Para simplificar los comandos de gcloud, configura el repositorio predeterminado como quickstart-ruby-repo y la ubicación predeterminada como us-west1. Una vez configurados los valores, no necesitas especificarlos en los comandos de gcloud que requieren un repositorio o una ubicación.

   Para configurar el repositorio, ejecuta el siguiente comando:

   gcloud config set artifacts/repository quickstart-ruby-repo
   

   Para configurar 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 establecimiento de la configuración de gcloud.

Descarga una 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, luego, descargarás una gem en él.

Para crear el directorio, ejecuta el siguiente comando:

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

A continuación, descarga tu gema. Puedes usar tu propia Gem o descargar una Gem de muestra desde la página Popular Gems en rubygems.org. Para descargar una gem de rubygems.org, ejecuta el siguiente comando:

gem fetch GEM_NAME

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

Envía la gem al repositorio

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

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

Aquí:

• GEM_NAME es el nombre de la gem que se enviará a tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

Visualiza la gem en el repositorio

Para verificar que se haya agregado tu gem, enumera los paquetes en el repositorio ruby-quickstart.

Ejecuta el comando siguiente:

gcloud artifacts packages list --repository=ruby-quickstart

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

gcloud artifacts versions list --package=GEM_NAME

Instala la gema

Para instalar la gem 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

Aquí:

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

Soluciona problemas

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

Realiza una limpieza

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta página.

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

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

   gcloud artifacts repositories delete quickstart-ruby-repo
   

2. Si deseas quitar la configuración predeterminada de la ubicación y del repositorio que estableciste para la configuración activa de gcloud, ejecuta los siguientes comandos:

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

¿Qué sigue?

• Obtén más información para configurar la autenticación.
• Obtén más información para administrar repositorios.
• Obtén más información para administrar paquetes.
• Lee nuestros recursos sobre DevOps y explora nuestro programa de investigación.