Almacena módulos de Go en Artifact Registry

Configura un repositorio privado de Go de Artifact Registry, sube un módulo a él y usa el módulo 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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. Instala Google Cloud CLI.

  6. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  7. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  9. Verify that billing is enabled for your Google Cloud project.

  10. Enable the Artifact Registry API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  11. Instala Google Cloud CLI.

  12. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  13. Para inicializar gcloud CLI, ejecuta el siguiente comando: 

    gcloud init
  14. Instala Go1.15 o una versión posterior.
  15. Instala el complemento package-go-module de gcloud CLI: 
    gcloud components install package-go-module

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar repositorios de módulos de Go de Artifact Registry, pídele a tu administrador que te otorgue el rol de IAM de administrador de Artifact Registry (roles/artifactregistry.admin) en tu proyecto. 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 mediante roles personalizados o cualquier otro rol predefinido.

Crea 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 predeterminado . Para ver una lista de las ubicaciones compatibles, ejecuta el siguiente 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 para los valores de proyecto, repositorio y ubicación. Una vez que se configuran los valores predeterminados, no se necesitan las etiquetas --project, --location y --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 los directorios 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!"

Empaqueta y sube 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 con el ID del proyecto 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 con la versión semántica del módulo en el formulario 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.

Enumera 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

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

Visualiza los 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 configuran 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 omita la base de datos de sumas de comprobación.

Configura 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, 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 Google Cloud .
    • REPOSITORY es el nombre del repositorio en el que se almacena el paquete.

  2. Excluye tu módulo de la comprobación con la base de datos pública de sumas de comprobación:

      export GONOSUMDB=MODULE_PATH_REGEX

    Reemplaza MODULE_PATH_REGEX por la ruta de acceso del módulo o una expresión regular si deseas excluir varios módulos.

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

      export GONOSUMDB=example.com/foo

    Si deseas 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 pública de sumas de comprobación, 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 de tu archivo netrc para autenticarse en Artifact Registry. Para simplificar el proceso de autenticación, puedes usar el auxiliar de credenciales de Go para actualizar los tokens en tu archivo netrc para la autenticación en Artifact Registry.

La ubicación de tu archivo netrc se puede establecer con la variable de entorno netrc. Si no se establece la variable NETRC, 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 tu 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 cuenta de servicio sin encriptar a tu archivo netrc.

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 a Go a descargarlo directamente desde GitHub. Si tienes otros módulos que deseas descargar directamente desde la fuente, puedes agregarlos en una lista separada por comas, como se muestra en el siguiente ejemplo:

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

En el que MODULE_PATH1 y MODULE_PATH2 son rutas de acceso de módulos que se descargarán de la fuente.

Para agregar el auxiliar de credenciales de Go a tu lista GONOPROXY y ejecutarlo para 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 a tu archivo netrc con la herramienta de paquete de módulos de 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]

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

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

Usa tu módulo como dependencia

  1. Si usas credenciales de corta duración para autenticarte en Artifact Registry, deberás 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 los directorios 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 tu 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 requerido.
    • 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 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 Google Cloud cuenta de por los recursos que usaste en esta página.

Sigue estos pasos para evitar que se apliquen cargos a tu Google Cloud cuenta de por los recursos que usaste en esta página. Antes de quitar el repositorio, asegúrate de que los módulos que quieres 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 con el ID del proyecto Google Cloud .
    • REPOSITORY por el nombre del repositorio.

  2. Si deseas quitar la configuración predeterminada de la ubicación y del repositorio 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?