Gerenciar módulos Go

Nesta página, explicamos 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 o Go 1.15 ou posterior.

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

    gcloud components install package-go-module

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

Papéis necessários

Para receber 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 como conceder papéis, consulte Gerenciar acesso.

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 pelo local regional ou multirregional do repositório.
  • MODULE_PATH pelo caminho do módulo. Por exemplo: example.com/foo Consulte a Referência de módulos Go para mais informações.
  • VERSION pela 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 sinalização --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 seu módulo para o projeto, o repositório e o local padrão quando os valores padrão estiverem configurados, execute o seguinte comando 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 VERSION e anexe os identificadores de pré-lançamento do seu 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 pontos. Por exemplo, para fazer upload do pré-lançamento de um módulo com o caminho do módulo example.com/foo identificado por alpha.x.12m.5, execute o comando abaixo:

  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 anteriores. Para evitar que os usuários importem uma alteração interruptiva, as versões principais após v1 precisam ter caminhos de módulo diferentes das versões anteriores. A partir do 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 nomeados com o 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, o repositório e o 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 do 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

Mais detalhes da versão do módulo

Modos de repositório:padrão

Execute o seguinte comando para visualizar 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 do Go em Configurar a autenticação para o Go.

  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@latest refresh

  2. Se o módulo ainda não tiver um arquivo go.mod, mude de diretório 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 armazenado no Artifact Registry, edite o arquivo go.mod para que 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 obrigató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 ter esta aparência:

      
  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 é transferido por download e usado como 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 uma versão específica.

  • Depois de excluir um pacote, não é possível desfazer a ação.

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]

Por

  • 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 ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o 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]

Por

  • 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 ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • --async retorna imediatamente, sem aguardar a conclusão da operação em andamento.

A seguir