Configura la autenticación en Artifact Registry para los repositorios de gemas de Ruby

En esta página, se describe cómo configurar la autenticación con un repositorio de gemas de Ruby de Artifact Registry.

Debes autenticarte en Artifact Registry cuando uses una aplicación de terceros para conectarte a un repositorio.

No es necesario que configures la autenticación para Cloud Build ni para los entornos de ejecución de Google Cloud, como Google Kubernetes Engine y Cloud Run.

Antes de comenzar

  1. Si el repositorio de destino no existe, crea un repositorio de gemas de Ruby.
  2. Verifica que Ruby esté instalado. Para obtener instrucciones de instalación, consulta elGoogle Cloud instructivo para configurar Ruby.
  3. Verifica que la cuenta de usuario o la cuenta de servicio que usas tenga los permisos necesarios para acceder al repositorio.

  4. Instala Google Cloud CLI y, luego, accede a gcloud CLI con tu identidad federada. Después de acceder, inicializa Google Cloud CLI con el siguiente comando: 

    gcloud init
  5. (Opcional) Configura valores predeterminados para gcloud CLI de gcloud.

Descripción general

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.

Genera tokens para la autenticación

Para autenticar tu paquete en Artifact Registry, primero debes generar un token de autenticación. Luego, puedes usar este token cuando realices solicitudes desde tu paquete a Artifact Registry.

Puedes generar un token de acceso oauth2 con Google Cloud o un token oauth2l fuera de Google Cloud.

Los tokens de acceso son válidos durante 60 minutos. Genera un token de acceso poco antes de ejecutar comandos que interactúen con repositorios. Si tu token de acceso venció, debes generar uno nuevo.

Genera un token con gcloud

Para generar un token de acceso de oauth2 con Google Cloud, ejecuta el siguiente comando:

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

Ahora puedes hacer referencia a ACCESS_TOKEN cuando realices solicitudes desde tu paquete de Ruby a Artifact Registry.

Genera un token sin usar gcloud

Para generar un token de acceso solo con la CLI de oauth2l, haz lo siguiente:

  1. Ejecuta el siguiente comando para instalar la versión más reciente de oauth2l:

    go install github.com/google/oauth2l@latest

  2. Ejecuta el comando siguiente:

    export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"

    Google Cloud genera un token de hash SHA256 y lo almacena en la variable ACCESS_TOKEN. Ahora puedes hacer referencia a ACCESS_TOKEN cuando realices solicitudes desde tu paquete de Ruby a Artifact Registry.

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, debes pasar tu token de OAuth2 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:

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

Para autenticar una versión de gem específica, 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 ACCESS_TOKEN retrieved from export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://ACCESS_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY/
<...>

Aquí:

  • ACCESS_TOKEN es tu token de acceso de OAuth2.
  • 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.

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

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. 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 ACCESS_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.
      • ACCESS_TOKEN es tu token de acceso de OAuth2.

    2. Empuja tu Gem. Ten en cuenta que no es necesario que establezcas el parámetro 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.

¿Qué sigue?