Gerenciar módulos Go

Esta página explica como gerenciar módulos Go empacotados armazenados no Artifact Registry.

Antes de começar

  1. Se não existir um repositório de destino, crie um novo repositório. Escolha Go como o formato do repositório.
  2. Verifique se você tem as permissões necessárias para o repositório.
  3. (Opcional) Configure padrões para comandos gcloud.
  4. Instale Go 1.15 ou mais recente.

  5. Instale o complemento package-go-module da CLI gcloud:

    gcloud components install package-go-module

  6. Configure o Go para autenticar com o Artifact Registry.

Papéis necessários

Para conseguir as permissões necessárias para gerenciar módulos, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:

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 por meio de papéis personalizados ou de outros papéis predefinidos.

Fazer upload de um módulo

Modos de repositório: padrão

Para empacotar e fazer upload de um módulo para o repositório, execute o seguinte comando:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

Substitua:

  • PROJECT com o 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.
  • MODULE_PATH com o caminho do módulo. Por exemplo: example.com/foo 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 módulo é enviado para o Artifact Registry.

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

Fazer upload de uma nova versão do módulo

Modos de repositório: padrão

Para fazer upload de uma nova versão do módulo para o projeto, repositório e local padrão quando os valores padrão estiverem configurados, execute o comando abaixo com o novo número de versão:

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

Substitua VERSION pela versão do módulo atualizado. Por exemplo, para fazer upload da versão 0.1.1 de um módulo com o caminho example.com/foo, execute o comando abaixo:

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v0.1.1 \
      --source=SOURCE_LOCATION

Para marcar um módulo como uma versão de pré-lançamento, adicione um traço após o VERSION e anexe os identificadores de pré-lançamento do módulo:

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION-PRE_RELEASE_IDENTIFIERS \
      --source=SOURCE_LOCATION

Substitua PRE_RELEASE_IDENTIFIERS por caracteres alfanuméricos ASCII e hifens separados por ponto. Por exemplo, para fazer upload de uma versão prévia de um módulo com o caminho example.com/foo identificado por alpha.x.12m.5, execute o comando a seguir:

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v1.0.0-alpha.x.12m.5 \
      --source=SOURCE_LOCATION

Fazer upload de uma nova versão principal

Modos de repositório: padrão

As versões principais não são compatíveis com versões anteriores. Para evitar que os usuários importem uma mudança interruptiva, as versões principais após v1 precisam ter caminhos de módulo diferentes das versões anteriores. A partir de v2, a versão principal é adicionada ao final do caminho do módulo.

Por exemplo, o caminho do módulo para v2.0.0 de example.com/foo seria example.com/foo/v2.

A prática recomendada é desenvolver versões principais após v1 em diretórios separados com o nome do sufixo da versão principal.

Para fazer upload de uma nova versão principal 2.0.0 de um módulo com o caminho example.com/foo para o projeto, repositório e local padrão quando os valores padrão estiverem configurados:

  gcloud artifacts go upload --module-path=example.com/foo/v2 --version=v2.0.0

Listar módulos

Modos de repositório: padrão

Execute o comando a seguir para inspecionar um 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á semelhante a esta:

  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

Modos de repositório: padrão

Execute o comando abaixo para conferir as versões de um 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á semelhante a esta:

  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

Usar um módulo como dependência

Modos de repositório: padrão

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 soma de verificação. Siga as instruções para configurar a autenticação e o ambiente Go em Configurar a autenticação para Go.

  1. Se você estiver usando credenciais de curta duração para fazer a 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@latest refresh

  2. Se o módulo ainda não tiver um arquivo go.mod, mude os diretórios para a pasta do módulo e execute go mod init para criar um arquivo go.mod para o pacote.

      go mod init MODULE_PATH

    Substitua MODULE_PATH pelo caminho do módulo armazenado no Artifact Registry. Consulte a Referência de módulos Go para mais informações.

  3. Para exigir a versão do módulo armazenada no Artifact Registry, edite o arquivo go.mod para que se pareça com este:

    
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

  4. Inclua o caminho do módulo normalmente na seção import do arquivo main.go.

    Por exemplo, para importar um módulo com o caminho example.com/foo armazenado no Artifact Registry, a seção de importação pode ser semelhante a esta:

      
  package main

  import (
    foo "example.com/foo"
  )

  func main() {

    ...

  }

  5. Execute go mod tidy para fazer o download de dependências:

      go mod tidy

  6. Execute o módulo normalmente:

      go run .

    O módulo armazenado no Artifact Registry é feito o download e usado como uma dependência.

Excluir módulos Go empacotados

Modos de repositório: padrão

É possível excluir um pacote e todas as versões dele ou excluir uma versão específica.

  • Não é possível desfazer a exclusão de um pacote.

Antes de excluir uma versão de pacote ou um pacote, verifique se você comunicou ou resolveu qualquer dependência importante nele.

Para excluir um pacote:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

  2. Na lista de repositórios, clique no repositório apropriado.

    A página Pacotes lista os pacotes no repositório.

  3. Selecione o pacote que você quer excluir.

  4. Clique em EXCLUIR.

  5. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Substitua:

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
  • LOCATION é o local regional ou multirregional do repositório. Use essa flag para conferir repositórios em um local específico. Se você configurou um local padrão, poderá omitir essa flag para usar o padrão.

A flag --async faz com que o comando seja retornado imediatamente, sem aguardar a conclusão da operação em andamento.

Para excluir versões de um pacote:

Console

  1. Abra a página Repositórios no console do Google Cloud.

    Abrir a página Repositórios

  2. Na lista de repositórios, clique no repositório apropriado.

    A página Pacotes lista os pacotes no repositório.

  3. Clique em um pacote para visualizar as versões dele.

  4. Selecione as versões que você quer excluir.

  5. Clique em EXCLUIR.

  6. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Substitua:

  • VERSION é o nome da versão a ser excluída.
  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
  • LOCATION é o local regional ou multirregional do repositório. Use essa flag para conferir repositórios em um local específico. Se você configurou um local padrão, poderá omitir essa flag para usar o padrão.

A flag --async faz com que o comando seja retornado imediatamente, sem aguardar a conclusão da operação em andamento.

A seguir