Armazenar módulos Go no Artifact Registry

Armazenar módulos Go no Artifact Registry

Configure um repositório Go do Artifact Registry privado, faça upload de um módulo para ele e use o módulo como uma dependência.

Antes de começar

1. Sign in to your Google Account.

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

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Artifact Registry API.

   Enable the API

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the Artifact Registry API.

   Enable the API

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
12. Instale o Go 1.15 ou mais recente.
13. Instale o complemento package-go-module da CLI gcloud:
    

    gcloud components install package-go-module

Crie um repositório

Para criar e configurar um novo repositório:

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

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

   Substitua:

   • REPOSITORY é o nome do repositório. Para cada local de repositório em um projeto, os nomes dos repositórios precisam ser exclusivos.
   • LOCATION é o local regional ou multirregional do repositório. É possível omitir essa flag se você definir um padrão. Para conferir uma lista de locais com suporte, execute o comando gcloud artifacts locations list.
   • DESCRIPTION é uma descrição opcional do repositório. Não inclua dados sensíveis, já que as descrições do repositório não são criptografadas.

2. Execute o comando a seguir para conferir os detalhes do repositório.

     gcloud artifacts repositories describe --location=LOCATION REPOSITORY
   

   A saída será assim:

     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'
   

Definir padrões para comandos gcloud

Você pode simplificar seus comandos gcloud CLI configurando os padrões para valores de projeto, repositório e local. Depois que os padrões forem configurados, as tags --project, --location e --repository não serão necessárias.

Empacotar e fazer upload de um módulo Go

O complemento da CLI gcloud package-go-module empacota seus módulos Go, permitindo que você faça a versão e o upload para o Artifact Registry usando o comando gcloud.

Criar um módulo Go

Primeiro, crie um módulo Go simples para fazer upload no repositório.

1. No diretório inicial, crie um diretório chamado "foo" para o módulo.

   mkdir foo
   

2. Mude os diretórios para o diretório do módulo e execute go mod init para criar um arquivo go.mod para o módulo.

     cd foo \
     go mod init example.com/foo
   

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

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

   
   package foo
   
   const HelloWorld = "Hello World!"
   

Empacotar e fazer upload do módulo

Empacote e faça upload do módulo para o repositório:

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

Substitua:

• PROJECT pelo do Google Cloud ID do projeto.
• REPOSITORY pelo nome do repositório em que o pacote está armazenado.
• LOCATION com o local regional ou multirregional do repositório.
• example.com/foo com o caminho do módulo. Consulte a Referência de 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 do patch.
• SOURCE_LOCATION pelo caminho para o diretório raiz do módulo Go. Se você omitir a flag --source, o padrão será o diretório atual.

O módulo é enviado para o Artifact Registry.

Para mais informações sobre a criação de módulos Go, consulte este tutorial.

Listar módulos

Execute o comando a seguir para inspecionar o módulo Go enviado no projeto, repositório e local padrão quando os valores padrão estiverem configurados:

  gcloud artifacts packages list

A saída será assim:

  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

Conferir detalhes da versão do módulo

Execute o comando a seguir para conferir as versões do módulo no projeto, repositório e local padrão quando os valores padrão estiverem configurados:

  gcloud artifacts versions list --package=MODULE_PATH

A saída será assim:

  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

Fazer o download de módulos

Para importar módulos armazenados no Artifact Registry, é necessário instruir o Go a procurar dependências do Artifact Registry e ignorar o banco de dados de checksum.

Configurar o ambiente do Go

1. Instrua o Go a fazer o download de módulos do Artifact Registry, do proxy de módulo Go público e da origem nesta ordem:

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

   Substitua:

   • LOCATION é o local regional ou multirregional do repositório.
   • PROJECT é o ID do projeto do Google Cloud.
   • REPOSITORY é o nome do repositório em que o pacote está armazenado.

2. Exclua o módulo da verificação usando o banco de dados de soma de verificação pública:

     export GONOSUMDB=MODULE_PATH_REGEX
   

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

   Para excluir o módulo example.com/foo da verificação usando o banco de dados de soma de verificação público, execute o seguinte comando:

     export GONOSUMDB=example.com/foo
   

   Se você quiser que todos os módulos com caminhos de módulo que começam em example.com sejam excluídos da verificação usando o banco de dados de checksum público, execute o comando abaixo:

     export GONOSUMDB=example.com/*
   

Fazer autenticação no Artifact Registry

Ao fazer o download de módulos Go empacotados para usar como dependências do Artifact Registry, o binário Go usa as credenciais no arquivo netrc para autenticação no Artifact Registry. Para simplificar o processo de autenticação, use o auxiliar de credenciais do Go para atualizar os tokens no arquivo netrc para autenticação no Artifact Registry.

O local do arquivo netrc pode ser definido com a variável de ambiente netrc. Se a variável NETRC não estiver definida, o comando go vai ler $HOME/.netrc em plataformas semelhantes ao UNIX ou %USERPROFILE%\_netrc no Windows.

O Artifact Registry é compatível com os seguintes métodos de autenticação.

Credenciais de curta duração (recomendado)

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

Usar uma chave de conta de serviço

Use essa opção quando não for possível usar credenciais no seu ambiente para autenticação. Adicione a chave da conta de serviço não criptografada ao arquivo netrc.

Observação: as chaves de conta de serviço poderão causar problemas de segurança se não forem gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura do que as chaves de conta de serviço. Caso seja necessário autenticar com uma chave de conta de serviço, você será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

Adicionar o auxiliar de credenciais do Go a GONOPROXY

Antes de usar o auxiliar de credenciais do Go, você precisa adicioná-lo à lista GONOPROXY para forçar o Go a fazer o download diretamente do GitHub. Se você tiver outros módulos que quer que sejam transferidos por download diretamente da fonte, adicione-os em uma lista separada por vírgulas, conforme mostrado no exemplo abaixo:

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

Em que MODULE_PATH1 e MODULE_PATH2 são caminhos de módulos a serem transferidos por download da origem.

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

1. Adicionar o auxiliar de credenciais do Go ao GONOPROXY

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

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

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

   Em que LOCATION é o local regional ou multirregional do repositório. Para adicionar vários locais, insira-os como uma lista separada por vírgulas.

   O auxiliar de credenciais Go adiciona configurações ao arquivo netrc para autenticação no Artifact Registry. Se você transmitir a flag --json_key, a chave será adicionada ao arquivo netrc para autenticação de senha.

Usar o módulo como uma dependência

1. Se você estiver usando credenciais de curta duração para autenticação no Artifact Registry, será necessário atualizar seu token OAuth executando o seguinte comando:

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

2. No diretório principal, crie um diretório chamado "bar".

     mkdir bar
   

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

     cd bar \
     go mod init example.com/bar
   

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

4. Para exigir a versão do foo armazenada no Artifact Registry, edite o arquivo go.mod para que se pareça com o seguinte:

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

   Substitua:

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

5. Crie um arquivo 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 fazer o download de dependências, incluindo o pacote foo:

     go mod tidy
   

7. Execute o módulo de barra:

     go run .
   

   A saída será assim:

     Hello World!
   

Limpar

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

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga estas etapas. Antes de remover o repositório, verifique se os módulos que você quer manter estão disponíveis em outro local.

1. Para excluir o repositório:

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

   Substitua:

   • LOCATION com o local regional ou multirregional do repositório.
   • PROJECT pelo ID de projeto do Google Cloud.
   • REPOSITORY pelo nome do repositório.

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

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

A seguir

• Saiba como configurar a autenticação.
• Saiba como gerenciar repositórios.
• Saiba mais sobre como gerenciar módulos Go.
• Leia nossos recursos sobre DevOps e conheça o programa de pesquisa DevOps Research and Assessment.