Armazenar módulos Go no Artifact Registry

Com os repositórios Go do Artifact Registry, é possível armazenar, versionar e compartilhar módulos Go particulares entre seus projetos. Neste guia de início rápido, você vai criar um repositório, empacotar e fazer upload de um módulo de exemplo e importar o módulo como uma dependência.

Antes de começar

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se agora.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Artifact Registry API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

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

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Artifact Registry API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  11. Install the Google Cloud CLI.

  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init
  14. Instale a versão principal mais recente ou a segunda versão principal mais recente do Go. Versões anteriores não são compatíveis.
  15. Instale o complemento da CLI gcloud package-go-module: 
    gcloud components install package-go-module

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar repositórios de módulos do Go do Artifact Registry, peça ao administrador para conceder a você o papel do IAM de Administrador do Artifact Registry (roles/artifactregistry.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar 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 aceitos, 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 de repositórios 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

É possível simplificar os comandos do gcloud CLI configurando os padrões para valores de projeto, repositório e local. Depois que os padrões são configurados, as tags --project, --location e --repository não são mais necessárias.

Empacotar e fazer upload de um módulo Go

O complemento package-go-module da CLI gcloud empacota seus módulos Go, permitindo que você crie versões e faça 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 seu módulo.

    mkdir foo

  2. Mude 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 seu repositório:

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

Substitua:

  • PROJECT com o ID do projeto do Google Cloud.
  • 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 pelo caminho do módulo. Consulte a referência de módulos do 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 upload do módulo é feito para o Artifact Registry.

Para mais informações sobre como criar 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

Ver detalhes da versão do módulo

Execute o comando a seguir para conferir as versões do seu 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

Baixar módulos

Para importar módulos armazenados no Artifact Registry, instrua o Go a procurar dependências no Artifact Registry e ignorar o banco de dados de checksum.

Configurar o ambiente Go

  1. Instrua o Go a fazer o download de módulos do Artifact Registry, do proxy de módulo público do Go e, em seguida, da origem, nessa 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 seu Google Cloud.
    • REPOSITORY é o nome do repositório em que o pacote está armazenado.

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

      export GONOSUMDB=MODULE_PATH_REGEX

    Substitua MODULE_PATH_REGEX pelo caminho do módulo ou uma expressão regular se você quiser excluir vários módulos.

    Para excluir seu módulo example.com/foo da verificação usando o banco de dados público de checksum, 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 público de checksum, execute o comando a seguir:

      export GONOSUMDB=example.com/*

Autenticar 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 autenticar 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 auxiliar de credencial do 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 ambiente para autenticação. Adicione a chave da conta de serviço não criptografada ao arquivo netrc.

Adicione o auxiliar de credenciais do Go a GONOPROXY

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

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

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

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

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

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

  2. Execute o comando a seguir para adicionar suas credenciais do Artifact Registry ao arquivo 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]

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

    O auxiliar de credencial do 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 autenticar no Artifact Registry, será necessário atualizar o 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 diretório inicial, crie um diretório chamado "bar".

      mkdir bar

  3. Mude para o diretório do módulo e execute go mod init para criar um arquivo go.mod para seu 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 do Go para mais informações.

  4. Para exigir a versão de foo armazenada no Artifact Registry, edite o arquivo go.mod para que ele fique assim:

    
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 das dependências, incluindo o pacote foo:

      go mod tidy

  7. Execute o módulo de barras:

      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 as etapas abaixo.

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 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 com o ID do projeto do Google Cloud.
    • REPOSITORY com o nome do repositório.

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

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

A seguir