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.

在删除软件包或软件包版本之前，请确认您已在其中告知或解决任何重要依赖项。

如需删除软件包，请按如下所述操作：

控制台

1. 在 Google Cloud 控制台中打开代码库页面。

   Abre la página Repositorios.

2. 在代码库列表中，点击相应代码库。

   软件包页面列出代码库中的软件包。

3. 选择要删除的软件包。

4. 点击删除。

5. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

替换以下内容：

• PACKAGE 是代码库中的软件包名称。
• REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
• LOCATION 是代码库的区域位置。 使用此标志可查看特定位置的代码库。如果您配置了默认位置，则可以省略此标志以使用默认值。

--async 标志会导致命令立即返回，而无需等待正在进行的操作完成。

如需删除软件包的版本，请按如下所述操作：

控制台

1. 在 Google Cloud 控制台中打开代码库页面。

   Abre la página Repositorios.

2. 在代码库列表中，点击相应代码库。

   软件包页面列出代码库中的软件包。

3. 点击一个软件包以查看它的版本。

4. 选择您要删除的版本。

5. 点击删除。

6. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

替换以下内容：

• VERSION 是要删除的版本的名称。
• PACKAGE 是代码库中的软件包名称。
• REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
• LOCATION 是代码库的区域位置。 使用此标志可查看特定位置的代码库。如果您配置了默认位置，则可以省略此标志以使用默认值。

--async 标志会导致命令立即返回，而无需等待正在进行的操作完成。

Siguientes pasos

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