Administra módulos de Go

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

Antes de comenzar

1. Si el repositorio de destino no existe, crea un repositorio nuevo. Elige Go como el formato del repositorio.
2. Verifica que tengas los permisos necesarios para el repositorio.
3. (Opcional) Configura valores predeterminados para los comandos de gcloud.
4. Instala Go 1.15 o una versión posterior.

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

   gcloud components install package-go-module

6. Configura Go para la autenticación con Artifact Registry.

Funciones requeridas

Para obtener los permisos que necesitas para administrar módulos, pídele a tu administrador que te otorgue los siguientes roles de IAM 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)
• Agregar módulos a un repositorio: Escritor de Artifact Registry (roles/artifactregistry.writer)
• Borrar módulos: Administrador del repositorio de Artifact Registry (roles/artifactregistry.repoAdmin)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Sube 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

Reemplaza lo siguiente:

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

El módulo se sube a Artifact Registry.

Para obtener más información sobre la creación de módulos de Go, consulta este instructivo.

Sube una nueva versión del módulo

Modos de repositorio: estándar

Para subir una versión nueva de tu módulo al proyecto, el repositorio y la ubicación predeterminados cuando se configuran los valores predeterminados, 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

Reemplaza 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 de acceso 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 una versión preliminar, agrega un guion después de VERSION y agrega los identificadores de versión preliminar de tu módulo:

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

Reemplaza PRE_RELEASE_IDENTIFIERS por guiones y caracteres alfanuméricos ASCII separados por puntos. Por ejemplo, para subir una versión preliminar de un módulo con la ruta de acceso 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 guiones y caracteres alfanuméricos ASCII separados por puntos. No se admiten metadatos. Para obtener más información sobre el control de versiones, consulta Control de versiones semántico 2.0.0 y esta entrada de blog para obtener detalles específicos de Go.

Sube 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 rotundo, las versiones principales después de v1 deben tener rutas de acceso de módulo diferentes a las versiones anteriores. A partir de v2, la versión principal se agrega al final de la ruta de acceso del módulo.

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

La práctica recomendada es desarrollar versiones principales después de v1 en directorios separados con el nombre de su sufijo de versión principal.

Para subir una nueva versión principal 2.0.0 de un módulo con la ruta de acceso example.com/foo al proyecto, el repositorio y la ubicación predeterminados cuando se configuran los valores predeterminados, haz lo siguiente:

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

Enumera módulos

Modos de repositorio: estándar, remoto, 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 configuran los valores predeterminados:

  gcloud artifacts packages list

El resultado será similar al 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

Visualiza los detalles de la versión del módulo

Modos de repositorio: estándar, remoto, virtual

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

  gcloud artifacts versions list --package=MODULE_PATH

El resultado será similar al 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

Usa un módulo como dependencia

Modos de repositorio: estándar, remoto, virtual

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

1. Si usas credenciales de corta duración para la autenticación 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 los directorios a la carpeta del módulo y ejecuta go mod init para crear un archivo go.mod para tu paquete.

     go mod init MODULE_PATH
   

   Reemplaza MODULE_PATH por la ruta de acceso 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
   

   Reemplaza lo siguiente:

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

4. Incluye la ruta de acceso del módulo como de costumbre en la sección import de tu archivo main.go.

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

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

5. Ejecuta go mod tidy para descargar dependencias:

     go mod tidy
   

6. Ejecuta tu módulo como de costumbre:

     go run .
   

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

Borra módulos de Go empaquetados

Modos de repositorio: estándar, remoto

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

• Una vez que borras un paquete, no puedes deshacer la acción.

Antes de borrar un paquete o una versión de un paquete, verifica que se haya comunicado o abordado cualquier dependencia importante en este.

Para borrar un paquete, haz lo siguiente:

Console

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

   Abrir la página repositorios

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

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

3. Selecciona el paquete que deseas borrar.

4. Haz clic en BORRAR.

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

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

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

La marca --async hace que el comando se muestre de inmediato, sin necesidad de esperar a que se complete la operación en curso.

Para borrar versiones de un paquete, haz lo siguiente:

Console

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

   Abrir la página repositorios

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

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

3. Haz clic en un paquete para ver las versiones de este.

4. Selecciona las versiones que quieras borrar.

5. Haz clic en BORRAR.

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

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

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

La marca --async hace que el comando se muestre de inmediato, sin necesidad de esperar a que se complete la operación en curso.

¿Qué sigue?

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