Armazenar gems do Ruby no Artifact Registry

Armazenar gems do Ruby no Artifact Registry

Pré-lançamento

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

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

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
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.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Artifact Registry API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
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.

   Acesse o IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

5. Na lista Selecionar papel, escolha um.
6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
7. Clique em Salvar.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

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.

   Acesse o IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos principais, digite seu identificador de usuário. Normalmente, é o endereço de e-mail de uma Conta do Google.

5. Na lista Selecionar papel, escolha um.
6. Para conceder outros papéis, adicione-os clicando em Adicionar outro papel.
7. Clique em Salvar.

Iniciar o Cloud Shell

Neste guia de início rápido, você vai usar o Cloud Shell, um ambiente shell para gerenciar recursos hospedados noGoogle 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 console do Google Cloud .

   Google Cloud console

2. Na barra de ferramentas do console do Google Cloud , 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 é 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://$[e-mail]/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://[e-mail]/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

Observação: depois que GEM_HOST_API_KEY for definido, as solicitações de envio não precisarão transmitir o token OAuth2 no URL.

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.

Para mais informações sobre métodos de autenticação, consulte Configurar a autenticação no Artifact Registry para repositórios de gem 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 gemas 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 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.

Baixar 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 o comando a seguir:

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

Em seguida, baixe a gema. Você pode usar seu próprio gem ou baixar um gem de exemplo na página "Gems mais usados" em rubygems.org. Para baixar uma gem de rubygems.org, execute o seguinte comando:

gem fetch GEM_NAME

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

Envie 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 por push para o repositório.
• PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.

Ver a gem no repositório

Para verificar se a gema 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://$[e-mail]/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 flag for omitida, o projeto padrão ou atual será usado.

Solução de problemas

Consulte Solução de problemas para 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

• Saiba mais sobre como configurar a autenticação
• Saiba mais sobre como gerenciar repositórios
• Saiba mais sobre como gerenciar pacotes
• Leia nossos recursos sobre DevOps e conheça nosso programa de pesquisa.