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 authenticate 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 seu 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 pelo ID de projeto do Google Cloud;
  • REPOSITORY pelo nome do repositório em que o pacote está armazenado.
  • LOCATION com o modelo regional ou multirregional local do repositório.
  • MODULE_PATH pelo caminho do módulo. Por exemplo: example.com/foo Consulte a Referência dos módulos Go para mais informações.
  • VERSION com o 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 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 o 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 seguinte comando:

  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 separados por pontos caracteres e hifens. Por exemplo, para fazer upload de um pré-lançamento de um módulo com o caminho example.com/foo identificado por alpha.x.12m.5, execute o seguinte comando:

  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 as versões anteriores. Para evitar usuários de importar uma alteração interruptiva, as versões principais após v1 devem ter caminhos de módulo diferentes dos usados nas versões anteriores. A partir de v2, as principais version é 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 na classe projeto, repositório e local em que valores padrão são 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 a seguir para exibir as versões de um módulo na classe projeto, repositório e local em que valores padrão são 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 to procure dependências do Artifact Registry e ignore a soma de verificação. no seu banco de dados. Siga as instruções para configurar a autenticação e o Go em Configurar a autenticação para Go.

  1. Se você estiver usando credenciais de curta duração para autenticação para o Artifact Registry, atualize 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 da pasta do seu módulo e execute go mod init para criar um arquivo go.mod para seu pacote.

      go mod init MODULE_PATH

    Substitua MODULE_PATH pelo caminho do módulo armazenado no Artifact Registry. Consulte a Referência dos 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 como de costume na seção import do 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]

Onde

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional. Use esta sinalização para ver repositórios em um local específico. Se você configurado um local padrão, é possível omitir essa sinalização para padrão.
  • --async Retorna 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]

Onde

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.
  • --async retorna imediatamente, sem aguardar a conclusão da operação em andamento.

A seguir