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 por 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 sea similar 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.

Antes de eliminar un paquete o una versión de un paquete, comprueba que has comunicado o resuelto las dependencias importantes que tenga.

Para eliminar un paquete, sigue estos pasos:

Consola

1. Abre la página Repositorios en la consola de Google Cloud .

   Abre la página Repositorios.

2. En la lista de repositorios, haga clic en el repositorio correspondiente.

   En la página Paquetes se muestran los paquetes del repositorio.

3. Selecciona el paquete que quieras eliminar.

4. Haz clic en ELIMINAR.

5. En el cuadro de diálogo de confirmación, haz clic en ELIMINAR.

gcloud

Ejecuta el siguiente comando:

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

Haz los cambios siguientes:

• PACKAGE es el nombre del paquete en el repositorio.
• REPOSITORY es el nombre del repositorio. Si has configurado un repositorio predeterminado, puedes omitir esta marca para usar el predeterminado.
• LOCATION es la ubicación regional o multirregional del repositorio. Usa esta marca para ver los repositorios de una ubicación específica. Si has configurado una ubicación predeterminada, puedes omitir esta marca para usarla.

La marca --async hace que el comando se devuelva inmediatamente, sin esperar a que se complete la operación en curso.

Para eliminar versiones de un paquete, sigue estos pasos:

Consola

1. Abre la página Repositorios en la consola de Google Cloud .

   Abre la página Repositorios.

2. En la lista de repositorios, haga clic en el repositorio correspondiente.

   En la página Paquetes se muestran los paquetes del repositorio.

3. Haz clic en un paquete para ver sus versiones.

4. Selecciona las versiones que quieras eliminar.

5. Haz clic en ELIMINAR.

6. En el cuadro de diálogo de confirmación, haz clic en ELIMINAR.

gcloud

Ejecuta el siguiente comando:

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

Haz los cambios siguientes:

• VERSION es el nombre de la versión que se va a eliminar.
• PACKAGE es el nombre del paquete en el repositorio.
• REPOSITORY es el nombre del repositorio. Si has configurado un repositorio predeterminado, puedes omitir esta marca para usar el predeterminado.
• LOCATION es la ubicación regional o multirregional del repositorio. Usa esta marca para ver los repositorios de una ubicación específica. Si has configurado una ubicación predeterminada, puedes omitir esta marca para usarla.

La marca --async hace que el comando se devuelva inmediatamente, sin esperar a que se complete la operación en curso.

Siguientes pasos

• Prueba la guía de inicio rápido de Go.
• Descargar archivos individuales asociados a un módulo o una versión sin usar comandos de Go.