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 o Cloud Build ou ambientes de execução do Google Cloud, 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 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 CLI do Google Cloud. Após a instalação, inicialize a CLI do Google Cloud executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

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

Visão geral

O Ruby é compatível com dois métodos para autenticar solicitações ao repositório do Artifact Registry:

  • CLI do RubyGems: aceita solicitações push e pull. Essa CLI está disponível com Ruby por padrão. Ao se autenticar com o RubyGems, você precisa fazer isso sempre que enviar ou extrair uma solicitação para seu repositório.

  • CLI Bundler: aceita solicitações de envio. O Bundler armazena pacotes e upstream 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.

Fazer a autenticação com a CLI do RubyGems

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

Autenticar solicitações de pull

É 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 fazer a autenticação na versão mais recente da gem na sua solicitação de envio, execute o comando a seguir:

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$GEM_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 do gem para o 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 GEM_TOKEN retrieved from export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPO/
<...>

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 do gem para o 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. Gere um token de acesso OAuth2 executando o seguinte comando:

    gcloud auth print-access-token

    Esse token funciona como sua chave de API para o Artifact Registry.

  2. 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 OAUTH_TOKEN

      Em que:

      • RUBYGEMS_ORG_KEY é a chave de API de 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.
      • OAUTH_TOKEN é seu token de acesso do OAuth2.

    2. Envie o gem. 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 seu 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