Almacena módulos de Go en Artifact Registry

Almacena módulos de Go en Artifact Registry

Configura un repositorio privado de Go en Artifact Registry, sube un módulo a él y úsalo como dependencia.

Antes de comenzar

1. Accede a tu cuenta de Google.

   Si todavía no tienes una cuenta, regístrate para obtener una nueva.

2. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

3. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

4. Habilita la API de Artifact Registry.

   Habilita la API

5. Instala Google Cloud CLI.

6. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

   gcloud init

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

7. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

8. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

9. Habilita la API de Artifact Registry.

   Habilita la API

10. Instala Google Cloud CLI.

11. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

    gcloud init

    Nota: Si ya instalaste la CLI de gcloud, asegúrate de que tienes la versión más reciente mediante la ejecución de gcloud components update.
12. Instala Go 1.15 o una versión posterior.
13. Instala el complemento package-go-module de gcloud CLI:
    

    gcloud components install package-go-module

Crear un repositorio

Para crear y configurar un repositorio nuevo, haz lo siguiente:

1. Ejecuta el siguiente comando para crear un repositorio nuevo.

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

   Reemplaza lo siguiente:

   • REPOSITORY es el nombre del repositorio. Para la ubicación de cada repositorio en un proyecto, los nombres de los repositorios deben ser únicos.
   • LOCATION es la ubicación regional o multirregional del repositorio. Puedes omitir esta marca si estableces un valor default. Para ver una lista de 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 del repositorio no están encriptadas.

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

     gcloud artifacts repositories describe --location=LOCATION REPOSITORY
   

   El resultado se ve de la manera 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'
   

Establece valores predeterminados para los comandos de gcloud

Puedes simplificar los comandos de gcloud CLI si configuras los valores predeterminados de los valores de proyecto, repositorio y ubicación. Una vez que se configuran los valores predeterminados, no se necesitan las etiquetas --project, --location ni --repository.

Empaqueta y sube un módulo de Go

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

Crea un módulo de Go

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

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

   mkdir foo
   

2. Cambia de directorio 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
   

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

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

   
   package foo
   
   const HelloWorld = "Hello World!"
   

Cómo empaquetar y subir tu 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

Reemplaza lo siguiente:

• PROJECT por el ID del proyecto de Google Cloud.
• REPOSITORY por el nombre del repositorio en el que se almacena el paquete
• LOCATION por la ubicación regional o multirregional del repositorio.
• example.com/foo por la ruta de acceso del módulo 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 al directorio raíz de tu módulo de Go. Si omites la marca --source, el valor predeterminado será el directorio actual.

El módulo se sube a Artifact Registry.

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

Mostrar lista de 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 configuren los valores predeterminados:

  gcloud artifacts packages list

El resultado se ve de la manera 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 detalles de la versión del 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 se configuren los valores predeterminados:

  gcloud artifacts versions list --package=MODULE_PATH

El resultado se ve de la manera 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

Cómo descargar módulos

Para importar módulos almacenados en Artifact Registry, debes indicarle a Go que busque dependencias de Artifact Registry y que omita la base de datos de suma de verificación.

Cómo configurar el entorno de Go

1. Indícale a Go que descargue los módulos desde Artifact Registry, el proxy del módulo de Go público y, luego, la fuente en ese orden:

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

   Reemplaza lo siguiente:

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

2. Excluye el módulo para que no se verifique con la base de datos de suma de comprobación pública:

     export GONOSUMDB=MODULE_PATH_REGEX
   

   Reemplaza MODULE_PATH_REGEX por la ruta de acceso de tu módulo o una regex si deseas excluir varios módulos.

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

     export GONOSUMDB=example.com/foo
   

   Si quieres que todos los módulos con rutas de acceso de módulos que comiencen en example.com se excluyan de la comprobación con la base de datos de suma de comprobación pública, ejecuta el siguiente comando:

     export GONOSUMDB=example.com/*
   

Autentícate en Artifact Registry

Cuando descargas módulos de Go empaquetados para usarlos como dependencias de Artifact Registry, el objeto binario de Go usa las credenciales del archivo Netrc para autenticarse en Artifact Registry. Si quieres simplificar el proceso de autenticación, puedes usar el auxiliar de credenciales de Go para actualizar los tokens en el archivo Netrc y realizar la autenticación en Artifact Registry.

Puedes establecer la ubicación del archivo netrc con la variable de entorno netrc. Si la variable NETRC no está configurada, el comando go leerá $HOME/.netrc en plataformas similares a UNIX o %USERPROFILE%\_netrc en Windows.

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

Credenciales de corta duración (recomendado)

Usa la herramienta auxiliar de credenciales de Go de Artifact Registry para actualizar los tokens de autenticación en el archivo Netrc.

Usa una clave de cuenta de servicio

Usa esta opción cuando no puedas usar credenciales en tu entorno para la autenticación. Agrega la clave de la cuenta de servicio sin encriptar a tu archivo Netrc.

Nota: Las claves de cuenta de servicio son un riesgo de seguridad si no se administran de forma adecuada. Debes elegir una alternativa más segura a las claves de la cuenta de servicio siempre que sea posible. Si te debes autenticar con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones que se describen en Prácticas recomendadas para administrar claves de cuenta de servicio. Si no se te permite crear una clave de cuenta de servicio, es posible que la creación de claves de cuentas de servicio esté inhabilitada para tu organización. Para obtener más información, consulta Administra los recursos de la organización con seguridad de forma predeterminada.

Agrega el auxiliar de credenciales de Go a GONOPROXY.

Antes de usar el auxiliar de credenciales de Go, debes agregarlo a la lista GONOPROXY para forzar la descarga de Go directamente desde GitHub. Si quieres descargar otros módulos directamente de la fuente, puedes agregarlos 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 rutas de acceso de módulos de módulos que se descargarán desde la fuente.

Para agregar el auxiliar de credenciales de Go a la lista GONOPROXY y ejecútalo a fin de configurar tus credenciales, haz lo siguiente:

1. Agrega el auxiliar de credenciales de Go a tu GONOPROXY

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

2. Ejecuta el siguiente comando para agregar tus credenciales de Artifact Registry al archivo netrc con la herramienta del paquete de módulos de Go:

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

   En el ejemplo anterior, LOCATION es la ubicación regional o multirregional de tu repositorio. Para agregar varias ubicaciones, ingrésalas en una lista separada por comas.

   El auxiliar de credenciales de Go agrega parámetros de configuración a tu archivo Netrc para autenticarse en Artifact Registry. Si pasas la marca --json_key, la clave se agregará a tu archivo netrc para autenticar la contraseña.

Cómo usar tu módulo como dependencia

1. Si usas credenciales de corta duración para autenticarte en Artifact Registry, deberás actualizar el token de OAuth mediante la ejecución del siguiente comando:

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

2. En tu directorio principal, crea un directorio llamado “bar”

     mkdir bar
   

3. Cambia de directorio 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
   

   Reemplaza example.com/bar por la ruta de acceso 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 se vea de la siguiente manera:

   
   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 del módulo obligatorio.
   • v0.1.0 es la versión almacenada en Artifact Registry

5. Crea un archivo main.go en el 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 dependencias, incluido el paquete foo:

     go mod tidy
   

7. Ejecuta el módulo de barra:

     go run .
   

   El resultado se ve de la manera siguiente:

     Hello World!
   

Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que se usaron en esta página.

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

1. Para borrar el repositorio, haz lo siguiente:

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

   Reemplaza lo siguiente:

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

2. Si quieres quitar la configuración predeterminada del repositorio y de la ubicación que estableciste para la configuración activa de gcloud, ejecuta los siguientes comandos:

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

¿Qué sigue?

• Obtén más información para configurar la autenticación.
• Obtén más información para administrar repositorios.
• Obtén más información para administrar módulos de Go.
• Lee nuestros recursos sobre DevOps y explora el programa de investigación Investigación y evaluación de DevOps.