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

Nesta página, descrevemos como configurar a autenticação com um repositório de gem 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 ambientes de execução do Cloud Build ou do Cloud de Confiance by S3NS, 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 gem do Ruby.
  2. Verifique se o Ruby está instalado. Para instruções de instalação, consulte o Cloud de Confiance by S3NS 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 os padrões para comandos da CLI gcloud.

Visão geral

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

  • CLI do RubyGems: oferece suporte a solicitações de push e pull. Essa CLI está disponível com Ruby por padrão. Ao se autenticar com o RubyGems, é necessário fazer isso sempre que você enviar ou criar uma solicitação de envio para seu repositório.

  • CLI Bundler: compatível com solicitações de pull. O Bundler armazena pacotes e upstreams em um gemfile, permitindo que os usuários padronizem configurações em várias máquinas sem precisar autenticar cada solicitação de envio individual. No entanto, você ainda precisa reautenticar suas credenciais no Bundler de vez em quando.

    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, use esse token ao fazer solicitações do seu pacote para o Artifact Registry.

É possível gerar um token de acesso oauth2 usando Cloud de Confiance by S3NS ou um token oauth2l fora do Cloud de Confiance by S3NS.

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 expirou, gere um novo.

Gerar um token usando a gcloud

Para gerar um token de acesso oauth2 usando Cloud de Confiance by S3NS, execute o seguinte comando:

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

Agora é possível referenciar ACCESS_TOKEN ao fazer solicitações do seu pacote 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"

    Cloud de Confiance by S3NS gera um token de hash SHA256 e o armazena na variável ACCESS_TOKEN. Agora é possível referenciar ACCESS_TOKEN ao fazer solicitações do pacote Ruby para o Artifact Registry.

Fazer a autenticação com a CLI do RubyGems

A CLI RubyGems usa tokens OAuth2 para autenticar uma solicitação. Para transmitir tokens OAuth2 para chamadas aos repositórios do Artifact Registry, é necessário transmitir 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 envio

É 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 envio na linha de comando

Para autenticar a versão mais recente da gem na sua solicitação de envio, execute o comando a seguir:

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

Para autenticar uma versão específica do gem, 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 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 fontes em solicitações de pull 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 do 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 gem usando a origem ou as origens definidas no arquivo /.gemrc, execute:

gem install GEM_NAME

Autenticar solicitações de push

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

Autenticar solicitações de push na linha de comando

Para autenticar sua solicitação de push, 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 do repositório.
  • PROJECT é o ID do projeto que contém o repositório.
  • REPOSITORY é o ID do repositório.

Autenticar solicitações de push 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 extrair gems. Para configurar o arquivo de credenciais e autenticar suas fontes em solicitações de push, faça o seguinte:

  1. Atualize o arquivo de credenciais:

    1. Abra ~/.gem/credentials e adicione uma linha para seu repositório. A chave é o URL do repositório, e o valor é Bearer, seguido pelo seu 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 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 do OAuth2.

    2. Envie seu Gem. Observação: não é necessário definir o GEM_HOST_API_KEY, já que você definiu a chave no arquivo de credenciais.

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

Autenticar com o Bundler

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

  1. Adicione o endereço do seu repositório como um 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 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.

De vez em quando, você precisará se autenticar novamente no repositório remoto. 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