Armazene módulos Go no Artifact Registry

Configurar um repositório Go do Artifact Registry privado, carregar um módulo para o mesmo e usar 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.

    Go to project selector

  3. Verify 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. Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  7. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

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

    Go to project selector

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

  10. Enable the Artifact Registry API.

    Enable the API

  11. Install the Google Cloud CLI.

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

  13. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init
  14. Instale o Go 1.15 ou posterior.
  15. Instale o suplemento da CLI gcloud:
    package-go-module 
    gcloud components install package-go-module

    16. 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 predefinição. 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 inicial, 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 percurso 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 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.

    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 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 pacotes de módulos 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 de 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?