Configurar a autenticação no Artifact Registry para repositórios de gem do Ruby

Esta página descreve como configurar a autenticação com um repositório de gemas do Ruby do Artifact Registry.

É necessário se autenticar no Artifact Registry ao usar um aplicativo de terceiros para se conectar a um repositório.

Não é necessário configurar a autenticação para o Cloud Build ou Google Cloud ambientes de execução, como o Google Kubernetes Engine e o Cloud Run.

Antes de começar

  1. Se o repositório de destino não existir, crie um repositório de gemas do Ruby.
  2. Verifique se o Ruby está instalado. Para instruções de instalação, consulte o Google Cloud tutorial de configuração do Ruby.
  3. Verifique se a conta de usuário ou de serviço que você está usando tem as permissões necessárias para acessar o repositório.

  4. Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init
  5. (Opcional) Configure padrões para CLI gcloud CLI.

Visão geral

O Ruby oferece suporte a dois métodos para autenticar solicitações no repositório do Artifact Registry:

  • CLI do RubyGems: oferece suporte a solicitações de envio e recebimento. Essa CLI está disponível com o Ruby por padrão. Ao se autenticar com o RubyGems, você precisa se autenticar sempre que fizer uma solicitação de envio ou recebimento para o repositório.

  • CLI do Bundler: oferece suporte a solicitações de recebimento. O Bundler armazena pacotes e origens em um gemfile, o que permite que os usuários padronizem as configurações em várias máquinas sem precisar autenticar cada solicitação de envio individual. No entanto, ainda é necessário autenticar novamente suas credenciais no Bundler ocasionalmente.

    Para instalar a CLI do Bundler, insira gem install bundler.

Gerar tokens para autenticação

Para autenticar seu pacote no Artifact Registry, primeiro gere um token de autenticação. Em seguida, você pode usar esse token ao fazer solicitações do pacote para o Artifact Registry.

É possível gerar um token de acesso oauth2 usando Google Cloud ou um oauth2l token fora de Google Cloud.

Os tokens de acesso são válidos por 60 minutos. Gere um token de acesso pouco antes de executar comandos que interagem com repositórios. Se o token de acesso tiver expirado, gere um novo.

Gerar um token usando a gcloud

Para gerar um oauth2 token de acesso usando Google Cloud, execute o seguinte comando:

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

Agora você pode referenciar ACCESS_TOKEN ao fazer solicitações do pacote do Ruby para o Artifact Registry.

Gerar um token sem usar a gcloud

Para gerar um token de acesso usando apenas a CLI oauth2l, faça o seguinte:

  1. Instale a versão mais recente do oauth2l executando o seguinte comando:

    go install github.com/google/oauth2l@latest

  2. Execute este comando:

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

    Google Cloud gera um token de hash SHA256 e o armazena na variável ACCESS_TOKEN. Agora você pode referenciar ACCESS_TOKEN ao fazer solicitações do pacote do Ruby para o Artifact Registry.

Autenticar com a CLI do RubyGems

A CLI do RubyGems usa tokens OAuth2 para autenticar uma solicitação. Para transmitir tokens OAuth2 para chamadas aos repositórios do Artifact Registry, transmita o token Oauth2 com o endereço do repositório ao fazer uma solicitação. Os tokens têm um ciclo de vida de uma hora e precisam ser atualizados a cada hora.

Autenticar solicitações de recebimento

É possível autenticar uma solicitação de envio na linha de comando da Google Cloud CLI ou atualizando o arquivo .gemrc.

Autenticar solicitações de recebimento na linha de comando

Para autenticar a versão mais recente da gema na solicitação de envio, execute o seguinte comando:

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

Para autenticar uma versão específica da gema, adicione -v GEM_VERSION ao comando gem install.

Em que:

  • GEM_NAME é o nome da gema para a qual a solicitação é feita.
  • LOCATION é o local regional ou multirregional location do repositório.
  • PROJECT é o ID do projeto que contém o repositório.
  • REPOSITORY é o ID do repositório.

Autenticar em um arquivo .gemrc

É possível configurar o arquivo /.gemrc global ou específico do projeto para autenticar suas origens em solicitações de recebimento adicionando o seguinte:

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

Em que:

  • ACCESS_TOKEN é seu token de acesso OAuth2.
  • LOCATION é o local regional ou multirregional do repositório.
  • PROJECT é o ID do projeto que contém o repositório.
  • REPOSITORY é o ID do repositório.

Para instalar uma gema usando a origem ou as origens definidas no arquivo /.gemrc, execute:

gem install GEM_NAME

Autenticar solicitações de envio

É possível autenticar uma solicitação de envio na linha de comando da Google Cloud CLI ou atualizando o arquivo de credenciais.

Autenticar solicitações de envio na linha de comando

Para autenticar sua solicitação de envio, execute o seguinte comando:

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

Em que:

  • GEM_NAME é o nome da gema para a qual a solicitação é feita.
  • LOCATION é o local regional ou multirregional location do repositório.
  • PROJECT é o ID do projeto que contém o repositório.
  • REPOSITORY é o ID do repositório.

Autenticar solicitações de envio em um arquivo de credenciais

A ferramenta de linha de comando gem usa o arquivo ~/.gem/credentials para armazenar chaves de API para enviar e receber gemas. Para configurar o arquivo de credenciais para autenticar suas origens em solicitações de envio, faça o seguinte:

  1. Atualize o arquivo de credenciais:

    1. Abra ~/.gem/credentials e adicione uma linha para o repositório. A chave é o URL do repositório, e o valor é Bearer, seguido pelo token:

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

      Em que:

      • RUBYGEMS_ORG_KEY é a chave de API para RubyGems.org.
      • LOCATION é o local regional ou multirregional location do repositório.
      • PROJECT é o ID do projeto que contém o repositório.
      • REPOSITORY é o ID do repositório.
      • ACCESS_TOKEN é seu token de acesso OAuth2.

    2. Envie a gema. Não é necessário definir a GEM_HOST_API_KEY, já que você já definiu a chave no arquivo de credenciais.

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

Autenticar com o Bundler

O Ruby Bundler gerencia dependências de aplicativos em uma ou mais gemas. Para configurar o Bundler, faça o seguinte:

  1. Adicione o endereço do repositório como uma source no gemfile:

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

  2. Autentique-se no repositório usando 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

Em que:

  • LOCATION é o local regional ou multirregional location do repositório.
  • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
  • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.

Será necessário autenticar novamente o repositório remoto ocasionalmente. Nesse caso, execute o mesmo comando de autenticação da etapa 2.

Para mais informações sobre como configurar o Bundler, consulte Gemfiles na documentação do bundler.io.

A seguir