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

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

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 Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

      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 identificador de um utilizador num Workload Identity Pool. Para ver detalhes, consulte Represente utilizadores do pool de força de trabalho em políticas de IAM ou contacte o seu administrador.

   5. Clique em Selecionar uma função e, de seguida, pesquise a 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 vem 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 streams de carregamento 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 o endereço 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 atualizar 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 autenticar 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 num ficheiro .gemrc

   Pode configurar o seu 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 um token de acesso OAuth2 executando o seguinte comando:

      gcloud auth print-access-token

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

   2. Atualize o ficheiro de credenciais:

      1. Abra o ~/.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 o artigo 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 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 uma gema 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 o 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 a 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 ativa do gcloud, 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.