Gestionar módulos de Go

En esta página se explica cómo gestionar los módulos Go empaquetados almacenados en Artifact Registry.

Antes de empezar

1. Si el repositorio de destino no existe, crea uno. Elige Go como formato de repositorio.
2. Verifica que tienes los permisos necesarios para el repositorio.
3. (Opcional) Configura los valores predeterminados de los comandos de gcloud.
4. Instalar Go 1.15 o versiones posteriores.

5. Instala el complemento package-go-module de gcloud CLI:

   gcloud components install package-go-module

6. Configura Go para autenticarte con Artifact Registry.

Nota: Artifact Registry no admite la marca -tool del módulo Go.

Roles obligatorios

Para obtener los permisos que necesitas para gestionar módulos, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en el repositorio:

• Ver módulos: Lector de Artifact Registry (roles/artifactregistry.reader)
• Descargar o instalar módulos: Lector de Artifact Registry (roles/artifactregistry.reader)
• Añade módulos a un repositorio: Escritor de Artifact Registry (roles/artifactregistry.writer)
• Eliminar módulos: Administrador de repositorios de Artifact Registry (roles/artifactregistry.repoAdmin)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Subir un módulo

Modos de repositorio: estándar

Para empaquetar y subir un módulo a tu repositorio, ejecuta el siguiente comando:

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

Haz los cambios siguientes:

• PROJECT con tu Google Cloud ID de proyecto.
• REPOSITORY con el nombre del repositorio en el que se almacena el paquete.
• LOCATION con la ubicación regional o multirregional del repositorio.
• MODULE_PATH con la ruta del módulo. Por ejemplo: example.com/foo Consulta la referencia de módulos de Go para obtener más información.
• VERSION con la versión semántica del módulo en el formato vX.Y.Z, donde X es la versión principal, Y es la versión secundaria y Z es la versión del parche.
• SOURCE_LOCATION con la ruta al directorio raíz de tu módulo de Go. Si omite la marca --source, se usará el directorio actual de forma predeterminada.

El módulo se sube a Artifact Registry.

Para obtener más información sobre cómo crear módulos de Go, consulta este tutorial.

Subir una nueva versión del módulo

Modos de repositorio: estándar

Para subir una nueva versión de tu módulo al proyecto, repositorio y ubicación predeterminados cuando los valores predeterminados estén configurados, ejecuta el siguiente comando con el nuevo número de versión:

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

Sustituye VERSION por la versión de tu módulo actualizado. Por ejemplo, para subir la versión 0.1.1 de un módulo con la ruta example.com/foo, ejecuta el siguiente comando:

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

Para marcar un módulo como versión preliminar, añade un guion después de VERSION y añade los identificadores de la versión preliminar del módulo:

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

Sustituye PRE_RELEASE_IDENTIFIERS por caracteres alfanuméricos ASCII separados por puntos y guiones. Por ejemplo, para subir una versión preliminar de un módulo con la ruta example.com/foo, identificada por alpha.x.12m.5, ejecuta el siguiente comando:

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

Nota: Los identificadores de versión preliminar deben ser caracteres alfanuméricos ASCII y guiones separados por puntos. Los metadatos no se admiten. Para obtener más información sobre el control de versiones, consulta Semantic versioning 2.0.0 y esta entrada de blog para ver detalles específicos de Go.

Subir una nueva versión principal

Modos de repositorio: estándar

Las versiones principales no son retrocompatibles con las versiones anteriores. Para evitar que los usuarios importen un cambio incompatible, las versiones principales posteriores a v1 deben tener rutas de módulo diferentes a las de las versiones anteriores. A partir de v2, la versión principal se añade al final de la ruta del módulo.

Por ejemplo, la ruta del módulo de v2.0.0 de example.com/foo sería example.com/foo/v2.

La práctica recomendada es desarrollar las versiones principales después de v1 en directorios independientes que tengan el nombre del sufijo de la versión principal.

Para subir una nueva versión principal 2.0.0 de un módulo con la ruta example.com/foo al proyecto, repositorio y ubicación predeterminados cuando los valores predeterminados estén configurados, sigue estos pasos:

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

Mostrar módulos

Modos de repositorio: estándar, remoto y virtual

Ejecuta el siguiente comando para inspeccionar un módulo de Go subido en el proyecto, el repositorio y la ubicación predeterminados cuando se hayan configurado los valores predeterminados:

  gcloud artifacts packages list

La salida será similar a la siguiente:

  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 los detalles de la versión de un módulo

Modos de repositorio: estándar, remoto y virtual

Ejecuta el siguiente comando para ver las versiones de un módulo en el proyecto, el repositorio y la ubicación predeterminados cuando los valores predeterminados estén configurados:

  gcloud artifacts versions list --package=MODULE_PATH

La salida será similar a la siguiente:

  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 un módulo como dependencia

Modos de repositorio: estándar, remoto y virtual

Para importar módulos almacenados en Artifact Registry, debes indicar a Go que busque dependencias en Artifact Registry y que omita la base de datos de sumas de comprobación. Sigue las instrucciones para configurar la autenticación y el entorno de Go en Configurar la autenticación para Go.

1. Si usas credenciales de corta duración para autenticarte en Artifact Registry, debes actualizar tu token de OAuth ejecutando el siguiente comando:

     GOPROXY=proxy.golang.org \
     go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@latest refresh
   

2. Si tu módulo aún no tiene un archivo go.mod, cambia de directorio a la carpeta de tu módulo y ejecuta go mod init para crear un archivo go.mod para tu paquete.

     go mod init MODULE_PATH
   

   Sustituye MODULE_PATH por la ruta del módulo almacenado en Artifact Registry. Consulta la referencia de módulos de Go para obtener más información.

3. Para requerir la versión de tu módulo almacenada en Artifact Registry, edita tu archivo go.mod para que se parezca al siguiente:

   
   module example.com/bar
   
   go 1.19
   
   require example.com/foo v0.1.0
   

   Haz los cambios siguientes:

   • example.com/foo es la ruta del módulo obligatorio
   • v0.1.0 es la versión almacenada en Artifact Registry

4. Incluye la ruta del módulo de forma normal en la sección import de tu archivo main.go.

   Por ejemplo, para importar un módulo con la ruta example.com/foo almacenado en Artifact Registry, la sección de importación podría ser similar a la siguiente:

     
     package main
   
     import (
       foo "example.com/foo"
     )
   
     func main() {
   
       ...
   
     }
   
     
   

5. Ejecuta go mod tidy para descargar las dependencias:

     go mod tidy
   

6. Ejecuta el módulo de la forma habitual:

     go run .
   

   El módulo almacenado en Artifact Registry se descarga y se usa como dependencia.

Eliminar módulos Go empaquetados

Modos de repositorio: estándar y remoto

Puedes eliminar un paquete y todas sus versiones, o bien eliminar una versión específica.

• Una vez que elimines un paquete, no podrás deshacer la acción.

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Abre la página Repositorios.

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Select the package that you want to delete.

4. Click DELETE.

5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Abre la página Repositorios.

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of that package.

4. Select versions that you want to delete.

5. Click DELETE.

6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

• VERSION is the name of the version to delete.
• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

Siguientes pasos

• Prueba la guía de inicio rápido de Go.