Armazene gems Ruby no Artifact Registry

Armazene gems Ruby no Artifact Registry

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais do Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Este início rápido mostra como configurar um repositório Ruby do Artifact Registry privado e, em seguida, carregar um pacote, também denominado 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.

   Aceder ao IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email de uma Conta Google.

5. Na lista Selecionar uma função, selecione uma função.
6. Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
7. Clique em Guardar.

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.

   Aceder ao IAM
2. Selecione o projeto.
3. Clique em Conceder acesso.

4. No campo Novos responsáveis, introduza o identificador do utilizador. Normalmente, este é o endereço de email de uma Conta Google.

5. Na lista Selecionar uma função, selecione uma função.
6. Para conceder funções adicionais, clique em Adicionar outra função e adicione cada função adicional.
7. Clique em Guardar.

Inicie o Cloud Shell

Neste início rápido, vai usar o Cloud Shell, que é um ambiente de shell para gerir recursos alojados no Google Cloud.

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

Inicie o Cloud Shell:

1. Aceda à Google Cloud consola.

   Google Cloud consola

2. Na Google Cloud barra de ferramentas da consola, clique em Ativar Cloud Shell.

É aberta uma sessão do Cloud Shell num frame na parte inferior da consola. Use esta shell para executar comandos gcloud.

Configure a autenticação

O Ruby suporta dois métodos para autenticar pedidos ao seu repositório do Artifact Registry:

• CLI do RubyGems: suporta pedidos de envio e obtenção. Esta CLI está disponível com o Ruby por predefinição. Quando se autentica com o RubyGems, tem de se autenticar sempre que faz um pedido push ou pull para o seu repositório.

• CLI Bundler: suporta pedidos de envio. O Bundler armazena pacotes e envios em um Gemfile, o que permite aos utilizadores padronizar as configurações em várias máquinas sem necessidade de autenticar cada pedido de obtenção individual. No entanto, tem de voltar a autenticar as suas credenciais no Bundler ocasionalmente.

  Para instalar a CLI Bundler, introduza gem install bundler.

Autentique com a CLI do RubyGems

A CLI RubyGems usa tokens OAuth2 para autenticar um pedido. Para transmitir tokens OAuth2 para chamadas aos seus repositórios do Artifact Registry, tem de primeiro gerar o token e, em seguida, transmiti-lo com a morada do seu repositório quando fizer um pedido. Os tokens têm uma duração de uma hora e têm de ser atualizados de hora a hora.

Autentique pedidos de envio

Pode autenticar um pedido de obtenção na linha de comandos da CLI do Google Cloud ou atualizando o ficheiro .gemrc.

Autentique pedidos de obtenção na linha de comandos

Para se autenticar na versão mais recente do gem no seu pedido de envio, execute o seguinte comando:

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$[e-mail]/PROJECT/REPOSITORY

Para fazer a autenticação para uma versão específica do gem, adicione -v GEM_VERSION ao comando gem install.

Onde:

• GEM_NAME é o nome da pedra preciosa para a qual o pedido é feito.
• LOCATION é a localização regional ou multirregional do repositório.
• PROJECT é o ID do projeto que contém o repositório.
• REPOSITORY é o ID do repositório.

Autentique-se num ficheiro .gemrc

Pode configurar o ficheiro /.gemrc global ou específico do projeto para autenticar as suas fontes em pedidos de obtenção 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 um gem através da origem ou das origens definidas no ficheiro /.gemrc, execute o seguinte comando:

gem install GEM_NAME

Autentique pedidos push

Pode autenticar um pedido push na linha de comandos da Google Cloud CLI ou atualizando o ficheiro de credenciais.

Autentique pedidos push na linha de comandos

Para autenticar o pedido 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

Nota: depois de GEM_HOST_API_KEY ter sido definido, os pedidos push não precisam de transmitir o token OAuth2 no URL.

Onde:

• GEM_NAME é o nome da pedra preciosa para a qual o pedido é feito.
• LOCATION é a localização regional ou multirregional do repositório.
• PROJECT é o ID do projeto que contém o repositório.
• REPOSITORY é o ID do repositório.

Autentique pedidos push num ficheiro de credenciais

A ferramenta de linha de comandos gem usa o ficheiro ~/.gem/credentials para armazenar chaves da API para enviar e extrair gems. Para configurar o ficheiro de credenciais para autenticar as suas fontes em pedidos push, faça o seguinte:

1. Gere uma chave de acesso OAuth2 executando o seguinte comando:

   gcloud auth print-access-token

   Este token funciona como a sua chave da API para o Artifact Registry.

2. Atualize o ficheiro de credenciais:

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

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

      Onde:

      • RUBYGEMS_ORG_KEY é a chave da API para RubyGems.org.
      • LOCATION é a localização 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 é a sua chave de acesso OAuth2.

   2. Empurre a gema. Tenha em atenção que não precisa de definir o GEM_HOST_API_KEY, uma vez que já definiu a chave no ficheiro de credenciais.

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

Autentique com o Bundler

O Bundler do Ruby gere as dependências das aplicações em um 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 através de 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
   

Onde:

• LOCATION é a localização regional ou multirregional do repositório.
• PROJECT é o ID do projeto. Se esta flag for omitida, é usado o projeto predefinido atual.
• REPOSITORY é o ID do repositório. Se configurou um repositório do Artifact Registry predefinido, este é usado quando esta flag é omitida do comando.

Tem de voltar a autenticar-se no repositório remoto ocasionalmente. Neste caso, execute o mesmo comando de autenticação do passo 2.

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

Para mais informações sobre os métodos de autenticação, consulte o artigo Configure a autenticação no Artifact Registry para repositórios de gemas Ruby.

Crie um repositório

Crie o repositório para a sua gem.

1. Execute o seguinte comando para criar um novo repositório de gemas Ruby no projeto atual denominado quickstart-ruby-repo na localização 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 predefinido como quickstart-ruby-repo e a localização predefinida como us-west1. Depois de definir os valores, não precisa de os especificar em gcloud comandos que requerem um repositório ou uma localização.

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

   gcloud config set artifacts/repository quickstart-ruby-repo
   

   Para definir a localização, execute o seguinte comando:

   gcloud config set artifacts/location us-west1
   

   Para mais informações sobre estes comandos, consulte a documentação do comando gcloud config set.

Transfira um gem

Quando cria um projeto Ruby, os ficheiros de distribuição são guardados numa subdiretoria lib no seu projeto Ruby. Para simplificar este guia de início rápido, vai criar um diretório e, em seguida, transferir um gem para esse diretório.

Para criar o diretório, execute o seguinte comando:

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

Em seguida, transfira o gem. Pode usar o seu próprio Gem ou transferir um Gem de exemplo da página Gems populares em rubygems.org. Para transferir um gem de rubygems.org, execute o seguinte comando:

gem fetch GEM_NAME

Agora, tem uma pedra preciosa com o título GEM_NAME no diretório ruby_quickstart/lib. Na secção seguinte, vai usar a CLI do RubyGems para enviar o seu gem para o repositório.

Envie o gem para o repositório

Para enviar o GEM para o seu repositório, execute o seguinte comando:

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

Onde:

• GEM_NAME é o nome do gem a enviar para o seu repositório.
• PROJECT é o ID do projeto. Se esta flag for omitida, é usado o projeto predefinido atual.

Veja a gema no repositório

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

Execute o seguinte 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

Instale o gem

Para instalar a gem que acabou de enviar para o 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

Onde:

• GEM_NAME é o nome do gem a instalar no seu repositório.
• PROJECT é o ID do projeto. Se esta flag for omitida, é usado o projeto predefinido atual.

Resolução de problemas

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

Limpar

Para evitar incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta página, siga estes passos.

Antes de remover o repositório, certifique-se de que todas as gems que quer manter estão disponíveis noutra localização.

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

   gcloud artifacts repositories delete quickstart-ruby-repo
   

2. Se quiser remover as definições predefinidas do repositório e da localização que configurou para a configuração gcloud ativa, execute os seguintes comandos:

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

O que se segue?

• Saiba mais sobre a configuração da autenticação
• Saiba como gerir repositórios
• Saiba como gerir pacotes
• Leia os nossos recursos sobre DevOps e explore o nosso programa de investigação.