Armazene módulos Go no Artifact Registry

Armazene módulos Go no Artifact Registry

Configure um repositório Go do Artifact Registry privado, carregue um módulo para o mesmo e use o módulo como uma dependência.

Antes de começar

Sign in to your Google Account.

If you don't already have one, sign up for a new account.

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

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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

Install the Google Cloud CLI.

Nota: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

1. Instale o Go 1.15 ou posterior.
2. Instale o suplemento da CLI gcloud:
   package-go-module

   gcloud components install package-go-module

Crie um repositório

Para criar e configurar um novo repositório:

1. Execute o seguinte comando para criar um novo repositório.

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=go \
       --location=LOCATION \
       --description=DESCRIPTION
   

   Substitua o seguinte:

   • REPOSITORY é o nome do repositório. Para cada localização do repositório num projeto, os nomes dos repositórios têm de ser exclusivos.
   • LOCATION é a localização regional ou multirregional para o repositório. Pode omitir esta flag se definir um valor predefinido. Para ver uma lista de localizações suportadas, execute o comando gcloud artifacts locations list.
   • DESCRIPTION é uma descrição opcional do repositório. Não inclua dados confidenciais, uma vez que as descrições dos repositórios não são encriptadas.

2. Execute o seguinte comando para ver os detalhes do repositório.

     gcloud artifacts repositories describe --location=LOCATION REPOSITORY
   

   O resultado é semelhante ao seguinte:

     Encryption: Google-managed key
     Repository Size: 0.000MB
     createTime: '2022-06-03T20:20:01.644813Z'
     format: GO
     mode: STANDARD_REPOSITORY
     name: projects/my-project/locations/us-west1/repositories/my-repo
     updateTime: '2022-06-03T20:20:01.644813Z'
   

Defina predefinições para comandos gcloud

Pode simplificar os comandos gcloud CLI configurando os valores predefinidos para os valores de projeto, repositório e localização. Depois de configurar as predefinições, não são necessárias as etiquetas --project, --location e --repository.

Empacote e carregue um módulo Go

Os pacotes de suplementos da CLI gcloud agrupam os seus módulos Go, o que lhe permite controlar as versões e carregá-los para o Artifact Registry através do comando gcloud.package-go-module

Crie um módulo Go

Primeiro, crie um módulo Go simples para carregar para o seu repositório.

1. No seu diretório pessoal, crie um diretório denominado "foo" para o seu módulo

   mkdir foo
   

2. Altere os diretórios para o diretório do seu módulo e execute go mod init para criar um ficheiro go.mod para o seu módulo.

     cd foo \
     go mod init example.com/foo
   

   Substitua example.com/foo pelo caminho do módulo. Consulte a referência dos módulos Go para mais informações.

3. Crie um ficheiro foo.go no diretório foo com o seguinte conteúdo:

   
   package foo
   
   const HelloWorld = "Hello World!"
   

Empacote e carregue o seu módulo

Empacote e carregue o módulo para o seu repositório:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=example.com/foo \
      --version=VERSION \
      --source=SOURCE_LOCATION

Substitua o seguinte:

• PROJECT com o seu Google Cloud ID do projeto.
• REPOSITORY com o nome do repositório onde o pacote está armazenado.
• LOCATION com a localização regional ou multirregional do repositório.
• example.com/foo com o caminho do módulo. Consulte a referência dos módulos Go para mais informações.
• VERSION com a versão semântica do módulo no formato vX.Y.Z, em que X é a versão principal, Y é a versão secundária e Z é a versão de patch.
• SOURCE_LOCATION com o caminho para o diretório raiz do seu módulo Go. Se omitir a flag --source, a predefinição é o diretório atual.

O módulo é carregado para o Artifact Registry.

Para mais informações sobre como criar módulos Go, consulte este tutorial.

Listar módulos

Execute o seguinte comando para inspecionar o módulo Go carregado no projeto, repositório e localização predefinidos quando os valores predefinidos estão configurados:

  gcloud artifacts packages list

O resultado é semelhante ao seguinte:

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

Veja os detalhes da versão do módulo

Execute o seguinte comando para ver as versões do seu módulo no projeto, repositório e localização predefinidos quando os valores predefinidos estão configurados:

  gcloud artifacts versions list --package=MODULE_PATH

O resultado é semelhante ao seguinte:

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

Transfira módulos

Para importar módulos armazenados no Artifact Registry, tem de indicar ao Go que procure dependências no Artifact Registry e ignore a base de dados de somas de verificação.

Configure o ambiente Go

1. Indique ao Go para transferir módulos do Artifact Registry, do proxy de módulos Go público e, em seguida, da origem nessa ordem:

     export GOPROXY=https://LOCATION-go.pkg.dev/PROJECT/REPOSITORY,https://proxy.golang.org,direct
   

   Substitua o seguinte:

   • LOCATION é a localização regional ou multirregional do repositório.
   • PROJECT é o seu Google Cloud ID do projeto.
   • REPOSITORY é o nome do repositório onde o pacote está armazenado.

2. Exclua o seu módulo da verificação através da base de dados de checksums pública:

     export GONOSUMDB=MODULE_PATH_REGEX
   

   Substitua MODULE_PATH_REGEX pelo caminho do módulo ou por uma regex se quiser excluir vários módulos.

   Para excluir o seu módulo example.com/foo da verificação através da base de dados de checksums públicos, execute o seguinte comando:

     export GONOSUMDB=example.com/foo
   

   Se quiser que todos os módulos com caminhos de módulos que comecem em example.com sejam excluídos da verificação através da base de dados de somas de verificação públicas, execute o seguinte comando:

     export GONOSUMDB=example.com/*
   

Autentique-se no Artifact Registry

Quando transfere módulos Go compactados para usar como dependências do Artifact Registry, o binário Go usa as credenciais no seu ficheiro netrc para autenticar no Artifact Registry. Para simplificar o processo de autenticação, pode usar o auxiliar de credenciais do Go para atualizar os tokens no ficheiro .netrc para autenticação no Artifact Registry.

A localização do ficheiro netrc pode ser definida com a variável de ambiente netrc. Se a variável NETRC não estiver definida, o comando go lê $HOME/.netrc em plataformas semelhantes ao UNIX ou %USERPROFILE%\_netrc no Windows.

O Artifact Registry suporta os seguintes métodos de autenticação.

Credenciais de curta duração (recomendado)

Use a ferramenta auxiliar de credenciais do Go do Artifact Registry para atualizar os tokens de autenticação no seu ficheiro netrc.

Use uma chave de conta de serviço

Use esta opção quando não puder usar credenciais no seu ambiente para autenticação. Adicione a chave da conta de serviço não encriptada ao ficheiro netrc.

Nota: As chaves de contas de serviço representam um risco de segurança se não forem geridas corretamente. Deve escolher uma alternativa mais segura às chaves de contas de serviço sempre que possível. Se tiver de fazer a autenticação com uma chave de conta de serviço, é responsável pela segurança da chave privada e por outras operações descritas nas Práticas recomendadas de gestão de chaves de conta de serviço. Se não conseguir criar uma chave de conta de serviço, a criação de chaves de contas de serviço pode estar desativada para a sua organização. Para mais informações, consulte o artigo Gerir recursos da organização seguros por predefinição.

Se adquiriu a chave da conta de serviço a partir de uma fonte externa, tem de a validar antes de a usar. Para mais informações, consulte os Requisitos de segurança para credenciais de origem externa.

Adicione o auxiliar de credenciais do Go a GONOPROXY

Antes de usar o auxiliar de credenciais do Go, tem de o adicionar à lista GONOPROXY para forçar o Go a transferi-lo diretamente do GitHub. Se tiver outros módulos que queira transferir diretamente da origem, pode adicioná-los numa lista separada por vírgulas, conforme mostrado no exemplo seguinte:

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

Onde MODULE_PATH1 e MODULE_PATH2 são caminhos de módulos a transferir da origem.

Para adicionar o auxiliar de credenciais do Go à sua lista de GONOPROXY e executá-lo para configurar as suas credenciais:

1. Adicione o auxiliar de credenciais do Go ao seu GONOPROXY

     export GONOPROXY=github.com/GoogleCloudPlatform/artifact-registry-go-tools
   

2. Execute o seguinte comando para adicionar as suas credenciais do Artifact Registry ao ficheiro netrc com a ferramenta de pacote do módulo Go:

     GOPROXY=proxy.golang.org \
         go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
         add-locations --locations=LOCATION \
         [--json_key=path/to/service/account/key.json]
   

   Onde LOCATION é a localização regional ou multirregional do seu repositório. Para adicionar várias localizações, introduza-as como uma lista separada por vírgulas.

   O auxiliar de credenciais do Go adiciona definições ao seu ficheiro netrc para autenticação no Artifact Registry. Se passar a flag --json_key, a chave é adicionada ao seu ficheiro netrc para autenticação por palavra-passe.

Use o seu módulo como uma dependência

1. Se estiver a usar credenciais de curta duração para autenticar no Artifact Registry, tem de atualizar o seu token OAuth executando o seguinte comando:

     GOPROXY=proxy.golang.org \
     go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 refresh
   

2. No seu diretório pessoal, crie um diretório denominado "bar"

     mkdir bar
   

3. Mude os diretórios para o diretório do seu módulo e execute go mod init para criar um ficheiro go.mod para o seu pacote.

     cd bar \
     go mod init example.com/bar
   

   Substitua example.com/bar pelo caminho do módulo. Consulte a referência dos módulos Go para mais informações.

4. Para exigir a versão de foo armazenada no Artifact Registry, edite o ficheiro go.mod para se assemelhar ao seguinte:

   
   module example.com/bar
   
   go 1.19
   
   require example.com/foo v0.1.0
   

   Substitua o seguinte:

   • example.com/foo é o caminho do módulo do módulo necessário
   • v0.1.0 é a versão armazenada no Artifact Registry

5. Crie um ficheiro main.go no diretório bar com o seguinte conteúdo:

     
     package main
   
     import (
       "fmt"
   
       foo "example.com/foo"
     )
   
     func main() {
       fmt.Println(foo.HelloWorld)
     }
   
     
   

6. Execute go mod tidy para transferir as dependências, incluindo o pacote foo:

     go mod tidy
   

7. Execute o módulo da barra:

     go run .
   

   O resultado é semelhante ao seguinte:

     Hello World!
   

Limpar

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

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 todos os módulos que quer manter estão disponíveis noutra localização.

1. Para eliminar o repositório:

     gcloud artifacts repositories delete \
         --location=LOCATION \
         --project=PROJECT \
         REPOSITORY
   

   Substitua o seguinte:

   • LOCATION com a localização regional ou multirregional do repositório.
   • PROJECT com o seu Google Cloud ID do projeto.
   • REPOSITORY com o nome do repositório.

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

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

O que se segue?

• Saiba mais acerca da configuração da autenticação.
• Saiba como gerir repositórios.
• Saiba como gerir módulos Go.
• Leia os nossos recursos sobre DevOps e explore o programa de investigação DevOps Research and Assessment.