Armazenar gems do Ruby no Artifact Registry

Neste guia de início rápido, mostramos como configurar um repositório privado do Artifact Registry Ruby e fazer upload de um pacote, também chamado de gem, para esse repositório.

Antes de começar

  1. 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.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. 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.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar repositórios de gems do Artifact Registry Ruby, peça ao administrador para conceder a você o papel do IAM de administrador do Artifact Registry (roles/artifactregistry.admin) no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Iniciar o Cloud Shell

Neste guia de início rápido, você usará o Cloud Shell, um ambiente shell para gerenciar recursos hospedados no Google Cloud.

O Cloud Shell vem pré-instalado com a Google Cloud CLI e o Ruby. A CLI gcloud fornece a principal interface de linha de comando para Google Cloud.

Inicie o Cloud Shell

  1. Acesse o Google Cloud console do.

    Google Cloud Console

  2. Na barra de ferramentas do Google Cloud console, clique em Ativar o Cloud Shell.

Uma sessão do Cloud Shell é aberta dentro de um quadro inferior no console. Use esse shell para executar comandos gcloud.

Configurar a autenticação

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

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

  • CLI Bundler: aceita solicitações de recebimento. O Bundler armazena pacotes e origens em um gemfile, 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 Bundler, insira gem install bundler.

Autenticar com a CLI 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 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 gem 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 gem, adicione -v GEM_VERSION ao comando gem install.

Em que:

  • GEM_NAME é o nome da gem 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 gem 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 a 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 gem 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 envio e recebimento de gems. 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 gem. 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 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 repositório como uma source no gemfile:

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

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

É necessário autenticar novamente no 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.

Para mais informações sobre métodos de autenticação, consulte Configurar a autenticação no Artifact Registry para repositórios de gems do Ruby.

Criar um repositório

Crie o repositório para sua gem.

  1. Execute o seguinte comando para criar um novo repositório de gems do Ruby no projeto atual chamado quickstart-ruby-repo no local us-west1.

    gcloud artifacts repositories create quickstart-ruby-repo \
    --repository-format=ruby \
    --location=us-west1 \
    --description="Ruby gem repository"

  2. Execute o seguinte comando para verificar se o repositório foi criado:

    gcloud artifacts repositories list

  3. Para simplificar os comandos gcloud, defina o repositório padrão como quickstart-ruby-repo e o local padrão como us-west1. Depois que os valores forem definidos, não será necessário especificá-los nos comandos gcloud que exigem um repositório ou local.

    Para definir o repositório, execute o seguinte comando:

    gcloud config set artifacts/repository quickstart-ruby-repo

    Para definir o local, execute o seguinte comando:

    gcloud config set artifacts/location us-west1

    Saiba mais sobre esses comandos na documentação do gcloud config set.

Fazer o download de uma gem

Ao criar um projeto Ruby, os arquivos de distribuição são salvos em um subdiretório lib no projeto Ruby. Para simplificar este guia de início rápido, você vai criar um diretório e fazer o download de uma gem para ele.

Para criar o diretório, execute este comando:

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

Em seguida, faça o download da gem. É possível usar sua própria gem ou fazer o download de uma gem de amostra na página Popular Gems (gems populares) em rubygems.org. Para fazer o download de uma gem do rubygems.org, execute o seguinte comando:

gem fetch GEM_NAME

Agora você tem uma gem chamada GEM_NAME no diretório ruby_quickstart/lib. Na próxima seção, você usará a CLI RubyGems para enviar a gem ao repositório.

Enviar a gem para o repositório

Para enviar a gem ao repositório, execute o seguinte comando:

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

Em que:

  • GEM_NAME é o nome da gem a ser enviada ao repositório.
  • PROJECT é o ID do projeto. Se essa sinalização for omitida, então o projeto atual ou padrão será usado.

Ver a gem no repositório

Para verificar se a gem foi adicionada, liste os pacotes no repositório ruby-quickstart.

Execute este comando:

gcloud artifacts packages list --repository=ruby-quickstart

Para ver as versões de uma gem, execute o seguinte comando:

gcloud artifacts versions list --package=GEM_NAME

Instalar a gem

Para instalar a gem que você acabou de enviar ao repositório do Artifact Registry, execute o seguinte comando:

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$GEM_TOKEN@us-west1-ruby.pkg.dev/PROJECT/quickstart-ruby-repo

Em que:

  • GEM_NAME é o nome da gem a ser instalada no repositório.
  • PROJECT é o ID do projeto. Se essa sinalização for omitida, então o projeto atual ou padrão será usado.

Solução de problemas

Consulte Solução de problemas de gems do Ruby para mais informações.

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga as etapas abaixo.

Antes de remover o repositório, verifique se as gems que você quer manter estão disponíveis em outro local.

  1. Para excluir o repositório quickstart-ruby-repo, execute o seguinte comando:

    gcloud artifacts repositories delete quickstart-ruby-repo

  2. Se você quiser remover as configurações padrão de repositório e localização que definiu para a configuração ativa gcloud, execute os seguintes comandos:

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

A seguir