Almacenar módulos de Go en Artifact Registry

Almacenar módulos de Go en Artifact Registry

Configura un repositorio de Go privado de Artifact Registry, sube un módulo y usa el módulo como dependencia.

Antes de empezar

Sign in to your Google Account.

If you don't already have one, sign up for a new account.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API.

Enable the API

Install the Google Cloud CLI.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry API.

Enable the API

Install the Google Cloud CLI.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

1. Instala Go 1.15 o una versión posterior.
2. Instala el complemento package-go-modulegcloud CLI
   :
   

   gcloud components install package-go-module

Crear un repositorio

Para crear y configurar un repositorio, sigue estos pasos:

1. Ejecuta el siguiente comando para crear un repositorio.

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=go \
       --location=LOCATION \
       --description=DESCRIPTION
   

   Haz los cambios siguientes:

   • REPOSITORY es el nombre del repositorio. Los nombres de los repositorios deben ser únicos en cada ubicación de repositorio de un proyecto.
   • LOCATION es la ubicación regional o multirregional del repositorio. Puedes omitir esta marca si defines un valor predeterminado. Para ver una lista de las ubicaciones admitidas, ejecuta el comando gcloud artifacts locations list.
   • DESCRIPTION es una descripción opcional del repositorio. No incluyas datos sensibles, ya que las descripciones de los repositorios no están cifradas.

2. Ejecuta el siguiente comando para ver los detalles del repositorio.

     gcloud artifacts repositories describe --location=LOCATION REPOSITORY
   

   La salida es similar a la siguiente:

     Encryption: Google-managed key
     Repository Size: 0.000MB
     createTime: '2022-06-03T20:20:01.644813Z'
     format: GO
     mode: STANDARD_REPOSITORY
     name: projects/my-project/locations/us-west1/repositories/my-repo
     updateTime: '2022-06-03T20:20:01.644813Z'
   

Configurar los valores predeterminados de los comandos de gcloud

Puedes simplificar tus comandos de gcloud CLI configurando los valores predeterminados de proyecto, repositorio y ubicación. Una vez que se hayan configurado los valores predeterminados, no será necesario usar las etiquetas --project, --location y --repository.

Empaquetar y subir un módulo de Go

Los paquetes complementarios de package-go-module gcloud CLI empaquetan tus módulos de Go, lo que te permite crear versiones y subirlas a Artifact Registry con el comando gcloud.

Crear un módulo de Go

Primero, crea un módulo de Go sencillo para subirlo a tu repositorio.

1. En tu directorio principal, crea un directorio llamado "foo" para tu módulo.

   mkdir foo
   

2. Cambia al directorio de tu módulo y ejecuta go mod init para crear un archivo go.mod para tu módulo.

     cd foo \
     go mod init example.com/foo
   

   Sustituye example.com/foo por la ruta del módulo. Consulta la referencia de módulos de Go para obtener más información.

3. Crea un archivo foo.go en el directorio foo con el siguiente contenido:

   
   package foo
   
   const HelloWorld = "Hello World!"
   

Empaquetar y subir un módulo

Empaqueta y sube el módulo a tu repositorio:

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=example.com/foo \
      --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.
• example.com/foo con la ruta del módulo. 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.

Mostrar módulos

Ejecuta el siguiente comando para inspeccionar el 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

La salida es 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

Ejecuta el siguiente comando para ver las versiones de tu 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 es 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

Descargar módulos

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.

Configurar el entorno de Go

1. Indica a Go que descargue módulos de Artifact Registry, el proxy público de módulos de Go y, a continuación, la fuente en ese orden:

     export GOPROXY=https://LOCATION-go.pkg.dev/PROJECT/REPOSITORY,https://proxy.golang.org,direct
   

   Haz los cambios siguientes:

   • LOCATION es la ubicación regional o multirregional del repositorio.
   • PROJECT es tu Google Cloud ID de proyecto.
   • REPOSITORY es el nombre del repositorio en el que se almacena el paquete.

2. Para excluir tu módulo de la comprobación mediante la base de datos pública de sumas de comprobación, sigue estos pasos:

     export GONOSUMDB=MODULE_PATH_REGEX
   

   Sustituye MODULE_PATH_REGEX por la ruta de tu módulo o por una expresión regular si quieres excluir varios módulos.

   Para excluir el módulo example.com/foo de la comprobación mediante la base de datos pública de sumas de comprobación, ejecuta el siguiente comando:

     export GONOSUMDB=example.com/foo
   

   Si quieres que todos los módulos con rutas de módulos que empiecen por example.com no se comprueben con la base de datos pública de sumas de comprobación, ejecuta el siguiente comando:

     export GONOSUMDB=example.com/*
   

Autenticarse en Artifact Registry

Cuando se descargan módulos Go empaquetados para usarlos como dependencias de Artifact Registry, el archivo binario Go usa las credenciales de tu archivo netrc para autenticarse en Artifact Registry. Para simplificar el proceso de autenticación, puedes usar el asistente de credenciales de Go para actualizar los tokens de tu archivo .netrc para autenticarte en Artifact Registry.

La ubicación del archivo netrc se puede definir con la variable de entorno netrc. Si no se define la variable NETRC, el comando go leerá $HOME/.netrc en plataformas de tipo UNIX o %USERPROFILE%\_netrc en Windows.

Artifact Registry admite los siguientes métodos de autenticación.

Credenciales de duración reducida (recomendado)

Usa la herramienta auxiliar de credenciales de Go de Artifact Registry para actualizar los tokens de autenticación de tu archivo .netrc.

Usar una clave de cuenta de servicio

Usa esta opción cuando no puedas usar credenciales en tu entorno para la autenticación. Añade la clave de cuenta de servicio sin cifrar al archivo .netrc.

Nota: Las claves de las cuentas de servicio suponen un riesgo para la seguridad si no se gestionan adecuadamente. Siempre que sea posible, deberías elegir una alternativa más segura a las claves de cuentas de servicio. Si debes autenticarte con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones descritas en las prácticas recomendadas para gestionar las claves de cuentas de servicio. Si no puedes crear una clave de cuenta de servicio, es posible que la creación de claves de cuenta de servicio esté inhabilitada en tu organización. Para obtener más información, consulta el artículo sobre gestionar recursos de organización seguros de forma predeterminada.

Si has obtenido la clave de cuenta de servicio de una fuente externa, debes validarla antes de usarla. Para obtener más información, consulta los requisitos de seguridad de las credenciales de fuentes externas.

Añadir el asistente de credenciales de Go a GONOPROXY

Antes de usar el asistente de credenciales de Go, debes añadirlo a la lista GONOPROXY para obligar a Go a descargarlo directamente de GitHub. Si tienes otros módulos que quieres descargar directamente de la fuente, puedes añadirlos en una lista separada por comas, como se muestra en el siguiente ejemplo:

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

Donde MODULE_PATH1 y MODULE_PATH2 son las rutas de los módulos que se van a descargar de la fuente.

Para añadir el asistente de credenciales de Go a tu lista de GONOPROXY y ejecutarlo para configurar tus credenciales, sigue estos pasos:

1. Añade el asistente de credenciales de Go a tu GONOPROXY

     export GONOPROXY=github.com/GoogleCloudPlatform/artifact-registry-go-tools
   

2. Ejecuta el siguiente comando para añadir tus credenciales de Artifact Registry al archivo .netrc con la herramienta de paquetes del módulo Go:

     GOPROXY=proxy.golang.org \
         go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 \
         add-locations --locations=LOCATION \
         [--json_key=path/to/service/account/key.json]
   

   Donde LOCATION es la ubicación regional o multirregional de tu repositorio. Para añadir varias ubicaciones, introdúzcalas en una lista separada por comas.

   El asistente de credenciales de Go añade ajustes a tu archivo netrc para autenticarte en Artifact Registry. Si pasas la marca --json_key, la clave se añade a tu archivo netrc para la autenticación con contraseña.

Usar tu módulo como dependencia

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

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

2. En tu directorio principal, crea un directorio llamado "bar".

     mkdir bar
   

3. Cambia al directorio de tu módulo y ejecuta go mod init para crear un archivo go.mod para tu paquete.

     cd bar \
     go mod init example.com/bar
   

   Sustituye example.com/bar por la ruta del módulo. Consulta la referencia de módulos de Go para obtener más información.

4. Para requerir la versión de foo almacenada en Artifact Registry, edita el 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

5. Crea un archivo main.go en tu directorio bar con el siguiente contenido:

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

6. Ejecuta go mod tidy para descargar las dependencias, incluido el paquete foo:

     go mod tidy
   

7. Ejecuta el módulo bar:

     go run .
   

   La salida es similar a la siguiente:

     Hello World!
   

Limpieza

Para evitar que se apliquen cargos en tu cuenta de Google Cloud por los recursos utilizados en esta página, sigue estos pasos.

Para evitar que se apliquen cargos en tu cuenta Google Cloud por los recursos utilizados en esta página, sigue estos pasos. Antes de quitar el repositorio, asegúrate de que los módulos que quieras conservar estén disponibles en otra ubicación.

1. Para eliminar el repositorio, sigue estos pasos:

     gcloud artifacts repositories delete \
         --location=LOCATION \
         --project=PROJECT \
         REPOSITORY
   

   Haz los cambios siguientes:

   • LOCATION con la ubicación regional o multirregional del repositorio.
   • PROJECT con tu Google Cloud ID de proyecto.
   • REPOSITORY con el nombre del repositorio.

2. Si quieres quitar los ajustes predeterminados de repositorio y ubicación que hayas configurado para la configuración de gcloud activa, ejecuta los siguientes comandos:

     gcloud config unset artifacts/repository
     gcloud config unset artifacts/location
   

Siguientes pasos

• Consulta más información sobre cómo configurar la autenticación.
• Consulta información sobre cómo gestionar repositorios.
• Consulta información sobre cómo gestionar módulos de Go.
• Consulta nuestros recursos sobre DevOps y descubre el programa de investigación DevOps Research and Assessment.