Stocker des modules Go dans Artifact Registry

Configurez un dépôt Go Artifact Registry privé, importez-y un module et utilisez-le comme dépendance.

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  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. Installez la Google Cloud CLI.

  6. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  7. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    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. Installez la Google Cloud CLI.

  12. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  13. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init
  14. Installez Go 1.15 ou une version ultérieure.
  15. Installez le module complémentaire package-go-module de la gcloud CLI : 
    gcloud components install package-go-module

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des dépôts de modules Go Artifact Registry, demandez à votre administrateur de vous accorder lerôle IAM Administrateur Artifact Registry (roles/artifactregistry.admin) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer un dépôt

Pour créer et configurer un dépôt :

  1. Exécutez la commande suivante pour créer un dépôt.

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

    Remplacez les éléments suivants :

    • REPOSITORY est le nom du dépôt. Pour chaque emplacement de dépôt d'un projet, les noms de dépôt doivent être uniques.
    • LOCATION est l'emplacement régional ou multirégional du dépôt. Vous pouvez omettre cet indicateur si vous définissez une valeur par défaut. Pour afficher la liste des emplacements compatibles, exécutez la commande gcloud artifacts locations list.
    • DESCRIPTION est une description facultative du dépôt. N'incluez pas de données sensibles, car les descriptions de dépôt ne sont pas chiffrées.

  2. Exécutez la commande suivante pour afficher les détails du dépôt.

      gcloud artifacts repositories describe --location=LOCATION REPOSITORY

    Le résultat se présente comme suit :

      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'

Définir des valeurs par défaut pour les commandes gcloud

Vous pouvez simplifier vos gcloud CLI commandes en configurant les valeurs par défaut pour le projet, le dépôt et l'emplacement. Une fois les valeurs par défaut configurées, les balises --project, --location et --repository ne sont plus nécessaires.

Empaqueter et importer un module Go

Le module complémentaire package-go-module de la gcloud CLI empaquète vos modules Go, ce qui vous permet de les versionner et de les importer dans Artifact Registry à l'aide de la commande gcloud.

Créer un module Go

Commencez par créer un module Go simple à importer dans votre dépôt.

  1. Dans votre répertoire d'accueil, créez un répertoire nommé "foo" pour votre module.

    mkdir foo

  2. Accédez au répertoire de votre module et exécutez go mod init pour créer un fichier go.mod pour votre module.

      cd foo \
  go mod init example.com/foo

    Remplacez example.com/foo par le chemin d'accès au module. Pour en savoir plus, consultez la documentation de référence sur les modules Go.

  3. Créez un fichier foo.go dans votre répertoire foo avec le contenu suivant :

    
package foo

const HelloWorld = "Hello World!"

Empaqueter et importer votre module

Empaquetez et importez le module dans votre dépôt :

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=example.com/foo \
      --version=VERSION \
      --source=SOURCE_LOCATION

Remplacez les éléments suivants :

  • PROJECT par l'ID de votre Google Cloud projet.
  • REPOSITORY par le nom du dépôt où le package est stocké.
  • LOCATION par l'emplacement régional ou multirégional emplacement du dépôt.
  • example.com/foo par le chemin d'accès au module. Pour en savoir plus, consultez la documentation de référence sur les modules Go.
  • VERSION par la version sémantique du module au format vX.Y.Z, où X correspond à la version majeure, Y à la version mineure et Z à la version de correctif.
  • SOURCE_LOCATION par le chemin d'accès au répertoire racine de votre Go module. Si vous omettez l'indicateur --source, le répertoire actuel est utilisé par défaut.

Le module est importé dans Artifact Registry.

Pour en savoir plus sur la création de modules Go, consultez ce tutoriel.

Lister les modules

Exécutez la commande suivante pour inspecter le module Go importé dans le projet, le dépôt et l'emplacement par défaut lorsque les valeurs par défaut sont configurées :

  gcloud artifacts packages list

Le résultat se présente comme suit :

  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

Afficher les détails de la version du module

Exécutez la commande suivante pour afficher les versions de votre module dans le projet, le dépôt et l'emplacement par défaut lorsque les valeurs par défaut sont configurées :

  gcloud artifacts versions list --package=MODULE_PATH

Le résultat se présente comme suit :

  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

Télécharger des modules

Pour importer des modules stockés dans Artifact Registry, vous devez demander à Go de rechercher les dépendances dans Artifact Registry et de contourner la base de données de sommes de contrôle.

Configurer l'environnement Go

  1. Demandez à Go de télécharger les modules à partir d'Artifact Registry, du proxy de module Go public, puis de la source dans cet ordre :

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

    Remplacez les éléments suivants :

    • LOCATION par l'emplacement régional ou multirégional emplacement du dépôt.
    • PROJECT par l'ID de votre Google Cloud projet.
    • REPOSITORY par le nom du dépôt où le package est stocké.

  2. Excluez votre module de la vérification à l'aide de la base de données de sommes de contrôle publique :

      export GONOSUMDB=MODULE_PATH_REGEX

    Remplacez MODULE_PATH_REGEX par le chemin d'accès à votre module ou par une expression régulière si vous souhaitez exclure plusieurs modules.

    Pour exclure votre module example.com/foo de la vérification à l'aide de la base de données de sommes de contrôle publique, exécutez la commande suivante :

      export GONOSUMDB=example.com/foo

    Si vous souhaitez que tous les modules dont le chemin d'accès commence par example.com soient exclus de la vérification à l'aide de la base de données de sommes de contrôle publique, exécutez la commande suivante :

      export GONOSUMDB=example.com/*

S'authentifier auprès d'Artifact Registry

Lorsque vous téléchargez des modules Go empaquetés à utiliser comme dépendances à partir d'Artifact Registry, le binaire Go utilise les identifiants de votre fichier netrc pour s'authentifier auprès d'Artifact Registry. Pour simplifier le processus d'authentification, vous pouvez utiliser l'assistant d'identification Go pour actualiser les jetons de votre fichier netrc afin de vous authentifier auprès d'Artifact Registry.

L'emplacement de votre fichier netrc peut être défini à l'aide de la variable d'environnement netrc. Si la variable NETRC n'est pas définie, la commande go lit $HOME/.netrc sur les plates-formes de type UNIX ou %USERPROFILE%\_netrc sur Windows.

Artifact Registry est compatible avec les méthodes d'authentification suivantes.

Identifiants de courte durée (recommandé)
Utilisez l'outil d'assistant d'identification Go Artifact Registry pour mettre à jour les jetons d'authentification dans votre fichier netrc.
Utiliser une clé de compte de service

Utilisez cette option lorsque vous ne pouvez pas utiliser d'identifiants dans votre environnement pour l'authentification. Ajoutez la clé de compte de service non chiffrée à votre fichier netrc.

Ajouter l'assistant d'identification Go à GONOPROXY

Avant d'utiliser l'assistant d'identification Go, vous devez l'ajouter à la liste GONOPROXY pour forcer Go à le télécharger directement depuis GitHub. Si vous souhaitez que d'autres modules soient téléchargés directement à partir de la source, vous pouvez les ajouter dans une liste séparée par des virgules, comme illustré dans l'exemple suivant :

  export GONOPROXY=MODULE_PATH1, MODULE_PATH2

Dans cette commande, MODULE_PATH1 et MODULE_PATH2 sont les chemins d'accès aux modules à télécharger à partir de la source.

Pour ajouter l'assistant d'identification Go à votre liste GONOPROXY et l'exécuter afin de configurer vos identifiants :

  1. Ajoutez l'assistant d'identification Go à votre liste GONOPROXY.

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

  2. Exécutez la commande suivante pour ajouter vos identifiants Artifact Registry à votre fichier netrc à l'aide de l'outil de package de module 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]

    Dans cette commande, LOCATION correspond à l'emplacement régional ou multirégional location de votre dépôt. Pour ajouter plusieurs emplacements, saisissez-les sous forme de liste séparée par des virgules.

    L'assistant d'identification Go ajoute des paramètres à votre fichier netrc pour l'authentification auprès d'Artifact Registry. Si vous transmettez l'indicateur --json_key, la clé est ajoutée à votre fichier netrc pour l'authentification par mot de passe.

Utiliser votre module comme dépendance

  1. Si vous utilisez des identifiants de courte durée pour vous authentifier auprès d'Artifact Registry, vous devez actualiser votre jeton OAuth en exécutant la commande suivante :

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

  2. Dans votre répertoire d'accueil, créez un répertoire nommé "bar".

      mkdir bar

  3. Accédez au répertoire de votre module et exécutez go mod init pour créer un fichier go.mod pour votre package.

      cd bar \
  go mod init example.com/bar

    Remplacez example.com/bar par le chemin d'accès au module. Pour en savoir plus, consultez la documentation de référence sur les modules Go.

  4. Pour exiger la version de foo stockée dans Artifact Registry, modifiez votre fichier go.mod comme suit :

    
module example.com/bar

go 1.19

require example.com/foo v0.1.0

    Remplacez les éléments suivants :

    • example.com/foo par le chemin d'accès au module requis.
    • v0.1.0 par la version stockée dans Artifact Registry.

  5. Créez un fichier main.go dans votre répertoire bar avec le contenu suivant :

      
  package main

  import (
    "fmt"

    foo "example.com/foo"
  )

  func main() {
    fmt.Println(foo.HelloWorld)
  }

  6. Exécutez go mod tidy pour télécharger les dépendances, y compris le package foo :

      go mod tidy

  7. Exécutez le module bar :

      go run .

    Le résultat se présente comme suit :

      Hello World!

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cette démonstration soient facturées sur votre Google Cloud compte pour les ressources utilisées sur cette page, procédez comme suit :

Pour éviter que les ressources utilisées dans cette démonstration soient facturées sur votre compte Google Cloud , procédez comme suit : Avant de supprimer le dépôt, assurez-vous que tous les modules que vous souhaitez conserver sont disponibles à un autre emplacement.

  1. Pour supprimer le dépôt :

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

    Remplacez les éléments suivants :

    • LOCATION par l'emplacement régional ou multirégional emplacement du dépôt.
    • PROJECT par l'ID de votre Google Cloud projet.
    • REPOSITORY par le nom du dépôt.

  2. Si vous souhaitez supprimer le dépôt par défaut et les paramètres d'emplacement que vous avez définis pour la configuration gcloud active, exécutez les commandes suivantes :

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

Étape suivante