gcloud compute

L'outil de ligne de commande gcloud compute vous permet de gérer facilement vos ressources Google Compute Engine et utilise un format plus convivial que celui de l'API Compute Engine.

Partie intégrante du gcloud, gcloud est un outil de ligne de commande unifié qui inclut des fonctionnalités telles que la saisie semi-automatique des instructions, la mise à jour sur place, une aide approfondie de type page de manuel, des formats de sortie lisibles et analysables, ainsi que l'intégration au SDK Google Cloud.

Si vous n'avez jamais utilisé Compute Engine, commencez par consulter l'un des guides de démarrage rapide.

Installer ou mettre à jour gcloud compute

  • Pour installer la dernière version de gcloud compute, installez le Google Cloud SDK.

  • Pour effectuer la mise à jour vers la dernière version de gcloud compute, consultez la section gcloud components update.

Configurer gcloud compute

Google Compute Engine utilise OAuth2 pour authentifier et autoriser l'accès. Avant de pouvoir utiliser gcloud compute, vous devez d'abord autoriser le SDK Cloud à accéder à votre projet en votre nom et acquérir un jeton d'authentification.

Si vous utilisez l'outil de ligne de commande gcloud pour la première fois, gcloud applique automatiquement la configuration default. Dans la plupart des cas, vous avez uniquement besoin de la configuration default.

  1. Exécutez gcloud init pour démarrer le processus d'authentification. Appuyez sur Entrée lorsque vous y êtes invité.

    La commande imprime une URL et tente d'ouvrir une fenêtre de navigateur pour demander l'accès à votre projet. Si une fenêtre de navigateur peut être ouverte, le résultat suivant s'affiche :

    gcloud init
    
    Welcome! This command will take you through the configuration of gcloud.
    
    Your current configuration has been set to: [default]
    
    ...
    
    To continue, you must login. Would you like to login (Y/n)?  y
    
    Your browser has been opened to visit:
    
    https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
    Fauth%2Fappengine.admin+https%3A%2F%2...

    Si le SDK Cloud détecte qu'un navigateur ne peut pas être ouvert (par exemple, si vous travaillez sur une machine distante), le résultat suivant s'affiche. Si vous travaillez sur un ordinateur local et que votre navigateur ne charge pas automatiquement l'URL, réessayez la commande gcloud init avec l'indicateur --console-only.

    gcloud init --console-only
    

    Copiez l'URL d'authentification et collez-la dans un navigateur. Puis recopiez le code de vérification dans le terminal.

    Go to the following link in your browser:
    
    https://accounts.google.com/o/oauth2/auth?scope=https%3A%2F%2Fwww.googleapis.co%2
    Fauth%2Fappengine.admin+https%3A%2F%2...
    
    Enter verification code:
  2. Accordez l'accès.

    Dans la fenêtre du navigateur, vérifiez les autorisations de l'application et cliquez sur Accepter lorsque vous êtes prêt. Si vous travaillez sur une machine à distance ou si vous avez utilisé l'indicateur --console-only, copiez et collez le code sur la ligne de commande après le message Saisissez le code de validation. Sinon, le code est automatiquement envoyé à l'outil de ligne de commande.

  3. Choisissez les identifiants pour cette configuration.

    Une fois la configuration des identifiants effectuée, gcloud vous invite à identifier un projet par défaut pour cette configuration. Sélectionnez un ID de projet dans la liste.

    Une fois cette propriété définie, toutes vos commandes gcloud compute utilisent l'ID de projet par défaut, sauf si vous le remplacez par l'indicateur --project ou définissez la variable d'environnement CLOUDSDK_CORE_PROJECT. Si vous ne définissez pas un projet par défaut ou une variable d'environnement, vous devez inclure un indicateur --project dans chaque commande gcloud compute que vous exécutez.

Une zone ou une région est requise pour utiliser des ressources appartenant à une zone ou à une région (par exemple, chaque fois que vous manipulez une instance de machine virtuelle, vous devez spécifier une zone). En définissant une zone et une région par défaut, gcloud peut utiliser ces informations sans vous obliger à les fournir à chaque demande. Vous pouvez également remplacer manuellement ces paramètres par défaut ou les modifier.

Pour en savoir plus, consultez la section Définir les propriétés par défaut.

Utiliser les configurations

gcloud utilise le concept de configurations pour vous aider à gérer vos identifiants pour différents comptes. Chaque configuration contient le compte de messagerie d'authentification, ainsi que des paramètres spécifiques tels que l'ID de projet par défaut, le paramètre de zone par défaut, etc. gcloud est automatiquement installé avec une configuration default. Il s'agit de la configuration dont les identifiants sont utilisés pour s'authentifier auprès des services Google Cloud Platform.

Pour la plupart des utilisateurs, la configuration default est suffisante. Pour les cas d'utilisation nécessitant le basculement d'un compte à un autre, vous pouvez créer d'autres configurations que vous pouvez alterner.

Consultez la page gcloud topic configurations pour obtenir des informations détaillées sur l'utilisation des configurations.

Définir les propriétés par défaut

Le serveur de métadonnées contient des informations de métadonnées sur le projet, par exemple son ID, son nom, etc. Vous pouvez interroger le serveur de métadonnées pour obtenir et utiliser les informations du projet.

Si vous spécifiez une région et une zone par défaut pour votre projet, Compute Engine définit ces valeurs dans le serveur de métadonnées de votre projet.

Les régions et zones par défaut sont définies à l'aide des valeurs suivantes :

  • google-compute-default-zone
  • google-compute-default-region

Pour voir quels sont vos paramètres de région et de zone par défaut, exécutez la commande gcloud suivante :

gcloud compute project-info describe --project [PROJECT_ID]

[PROJECT_ID] correspond à l'ID de votre projet.

Recherchez les clés et les valeurs de métadonnées suivantes dans la réponse :

- key: google-compute-default-region
  value: ...
- key: google-compute-default-zone
  value: ..

Si les clés et les valeurs google-compute-default-region et google-compute-default-zone ne figurent pas dans la réponse, cela signifie qu'aucune zone ou région par défaut n'est définie.

  • Si aucune valeur par défaut n'est définie, gcloud vous invite à saisir une région et une zone à chaque requête.
  • Si une valeur par défaut est définie, gcloud utilise automatiquement la valeur par défaut pour toutes vos requêtes gcloud, à moins que vous n'ignoriez manuellement les paramètres par défaut.

Pour modifier, définir ou ignorer les propriétés par défaut, utilisez les méthodes ci-dessous.

Modifier la zone et la région par défaut dans le serveur de métadonnées

Vous pouvez modifier la zone et la région par défaut de votre serveur de métadonnées en effectuant une demande auprès du serveur de métadonnées. Exemple :

gcloud compute project-info add-metadata \
    --metadata google-compute-default-region=europe-west1,google-compute-default-zone=europe-west1-b

L'outil de ligne de commande gcloud ne prend en compte que les changements de zone et de région par défaut après la réexécution de la commande gcloud init. Après avoir mis à jour vos métadonnées par défaut, lancez gcloud init pour réinitialiser votre configuration default.

Définir la zone et la région par défaut dans le client local

Vous pouvez choisir une zone ou une région différente manuellement sans mettre à jour le serveur de métadonnées en définissant ces propriétés localement sur le client gcloud.

Tout d'abord, assurez-vous que vous utilisez la configuration pour laquelle vous souhaitez que ces propriétés soient définies. Chaque configuration contient ses propres paramètres ; pour basculer entre les configurations, exécutez la commande suivante :

gcloud config configurations activate CONFIGURATION_NAME

Ensuite, pour définir une propriété de zone ou de région dans le client, exécutez la commande suivante :

gcloud config set compute/zone ZONE
gcloud config set compute/region REGION

Pour supprimer une propriété par défaut, utilisez la commande unset.

gcloud config unset compute/zone
gcloud config unset compute/region

Notez que si vous supprimez la propriété par défaut, gcloud demandera une zone ou une région pour chaque commande exécutée.

Définir les valeurs par défaut dans les variables d'environnement

Vous pouvez définir des variables d'environnement qui fournissent des valeurs aux commandes gcloud compute. Les variables d'environnement remplacent les propriétés par défaut que vous définissez avec les commandes gcloud config, mais ne remplacent pas les indicateurs explicites tels que --zone ou --region.

Linux/macOS
Utilisez la commande export pour définir les variables de zone et de région.
$ export CLOUDSDK_COMPUTE_ZONE=ZONE
$ export CLOUDSDK_COMPUTE_REGION=REGION
Pour rendre ces variables d'environnement permanentes, incluez ces commandes dans votre fichier ~/.bashrc et redémarrez votre terminal.
Windows
Utilisez la commande set pour définir les variables de zone et de région.
C:\> set CLOUDSDK_COMPUTE_ZONE=ZONE
C:\> set CLOUDSDK_COMPUTE_REGION=REGION

Vous pouvez remplacer les variables d'environnement en incluant des indicateurs --zone ou --region spécifiques avec vos commandes.

Définir des valeurs sur chaque demande

Vous pouvez remplacer les propriétés par défaut en incluant des indicateurs --zone ou --region spécifiques avec chacune de vos commandes. Exemple :

gcloud compute instances create example-instance --zone us-central1-f

Ces indicateurs ne fonctionnent qu'avec la commande unique que vous utilisez. Les indicateurs ne modifient aucun paramètre par défaut, mais le remplacent simplement pour cette demande.

Ordre d'application des propriétés par défaut

L'outil de ligne de commande gcloud évalue les propriétés par défaut dans l'ordre suivant pour chaque configuration :

  • Si vous fournissez un indicateur --zone, --region ou --project explicite, celui-ci remplace tous les autres paramètres associés à cette requête unique.
  • Si les propriétés de zone et de région par défaut sont définies uniquement sur le serveur de métadonnées, l'outil de ligne de commande gcloud définit ces propriétés sur votre client gcloud local lorsque vous exécutez gcloud init. Pour les requêtes ultérieures, l'outil vous invite à entrer la zone.
  • Si les propriétés de zone et de région par défaut sont définies à la fois sur le serveur de métadonnées et sur le client local associé à cette configuration, l'outil utilise les propriétés par défaut sur le client local.
  • Si les propriétés de zone et de région par défaut sont définies dans la serveur de métadonnées, le client local et les variables d'environnement, l'outil utilise les propriétés par défaut des variables d'environnement, quelle que soit la configuration utilisée.

Commandes gcloud compute courantes

Vous trouverez ci-dessous des exemples de tâches courantes lorsque vous utilisez des instances. Pour en savoir plus sur l'utilisation des instances en général, consultez la page Instances.

Créer des instances

Utilisez la commande instances create pour créer une instance. Par exemple, la commande suivante crée une instance nommée "my-instance" dans la zone "us-central1-a".

gcloud compute instances create my-instance

Si vous omettez l'indicateur --zone, gcloud peut déduire la zone souhaitée en fonction de vos propriétés par défaut.

Si les autres paramètres d'instance requis, tels que le type de machine et l'image, ne sont pas spécifiés dans la commande "create", ils sont définis sur les valeurs par défaut. Vous pouvez afficher les valeurs par défaut en accédant à l'aide associée à la commande create command :

gcloud compute instances create --help

Répertorier les instances

Il existe plusieurs manières d'obtenir la liste de vos instances à l'aide de la commande instances list. Vous pouvez créer une sortie tabulaire en format lisible à l'aide de la commande suivante :

gcloud compute instances list

Vous pouvez utiliser des expressions régulières pour affiner la liste des instances renvoyées grâce à un filtrage par nom. Par exemple, la commande suivante renvoie toutes les instances dont le nom commence par "my-".

gcloud compute instances list --filter="name ~ ^my-.*"

Pour plus d'informations sur la manière de répertorier et filtrer des ressources, consultez la section relative à la récupération de ressources.

Pour obtenir des détails sur une instance, utilisez la commande instances describe. Par exemple, la commande suivante renvoie des informations sur "my-instance".

gcloud compute instances describe my-instance --zone us-central1-a

La commande précédente renvoie des résultats au format YAML. Vous pouvez utiliser l'indicateur --format pour modifier l'affichage des résultats. Pour plus d'exemples sur l'obtention et l'affichage des ressources, y compris les instances, consultez la section relative à la récupération de ressources.

Se connecter aux instances

gcloud compute facilite la connexion à vos instances. Les commandes gcloud compute ssh et gcloud compute scp fournissent des wrappers SSH et SCP, lesquels assurent l'authentification et le mappage du nom d'instance sur l'adresse IP.

Par exemple, pour vous connecter via SSH à "my-instance" dans la zone "us-central1-a", vous pouvez utiliser la commande suivante :

gcloud compute ssh my-instance --zone us-central1-a

Pour copier le fichier local "file-1" dans "my-instance" dans la zone "us-central1-a", vous pouvez utiliser la commande suivante :

gcloud compute scp ~/file-1 my-instance:~/remote-destination --zone us-central1-a

La commande scp peut également être utilisée pour copier des fichiers d'une instance sur votre ordinateur local. Par exemple, pour créer une copie locale de "file-1", qui se trouve sur l'instance "my-instance", dans la zone "us-central1-a", vous pouvez utiliser la commande suivante :

gcloud compute scp my-instance:~/file-1 ~/local-destination --zone us-central1-a

Les commandes gcloud compute ssh et gcloud compute scp utilisent par défaut le fichier de clé privée se trouvant dans "~/.ssh/google_compute_engine". Si vous ne souhaitez pas utiliser ce fichier de clé, vous pouvez spécifier un fichier de clé différent en spécifiant un autre emplacement à l'aide de l'indicateur --ssh-key-file. Par exemple, vous pouvez déjà avoir une clé privée que vous souhaitez utiliser ou vous pouvez utiliser différentes clés privées avec différents projets.

Utiliser directement des programmes SSH

Si vous préférez utiliser ssh et scp directement, gcloud compute peut générer un fichier de configuration SSH contenant des alias d'hôte pour vos instances avec une configuration d'authentification. Pour ce faire, exécutez la commande suivante :

gcloud compute config-ssh

Voici un exemple d'alias ajouté au fichier de configuration SSH (~/.ssh/config) :

Host my-instance.us-central1-a.myproject
HostName 107.178.220.224
IdentityFile ~/.ssh/google_compute_engine
UserKnownHostsFile=/dev/null
CheckHostIP=no
StrictHostKeyChecking=no

Vous pouvez spécifier un autre fichier de configuration SSH par utilisateur à l'aide de l'indicateur --ssh-config-file.

Chaque fois que vous ajoutez ou supprimez une instance, vous devez exécuter à nouveau la commande config-ssh.

Après avoir mis à jour vos fichiers de configuration SSH avec la commande config-ssh, vous pouvez utiliser n'importe quel programme SSH pour accéder à vos instances. Par exemple, pour l'instance nommée "my-instance", dans la zone "us-central1-a", dans le projet nommé "myproject", vous pouvez utiliser le client SSH OpenSSH comme suit :

$ ssh my-instance.us-central1-a.myproject

Pour créer une copie locale du fichier "file-1" sur l'instance, vous pouvez utiliser le client scp comme suit :

$ scp my-instance.us-central1-a.myproject:~/file-1 .

Utiliser des métadonnées

Vous pouvez définir des métadonnées personnalisées pour une instance ou un projet en dehors des métadonnées définies sur le serveur. Ceci est utile pour transférer des valeurs arbitraires à votre projet ou à votre instance sur lesquelles des requêtes peuvent être émises via le code de l'instance. Cette section présente quelques opérations de métadonnées courantes. Pour plus d'informations sur l'utilisation des métadonnées, consultez la section relative au stockage et à la récupération de métadonnées.

Ajouter et supprimer les métadonnées d'une instance

Vous pouvez configurer les métadonnées d'une instance avec gcloud compute lorsque vous la créez à l'aide de la commande create, ou configurer celles d'une instance existante à l'aide des commandes add-metadata et remove-metadata. Les métadonnées sont spécifiées en tant que paires clé/valeur séparées par un signe égal ("=") à l'aide de l'indicateur --metadata. Les métadonnées peuvent être également lues à partir d'un fichier local à l'aide de l'indicateur --metadata-from-file.

Par exemple, pour ajouter les clés de métadonnées personnalisées "role", "unique-id" et "build-num" à une instance existante nommée "my-instance" dans la zone "us-central1-a", vous pouvez utiliser la commande suivante :

gcloud compute instances add-metadata my-instance \
    --zone us-central1-a \
    --metadata role=worker unique-id=1234 build-num=4.32

Pour supprimer les clés de métadonnées personnalisées "role" et "unique-id", vous pouvez utiliser la commande suivante :

gcloud compute instances remove-metadata my-instance \
    --zone us-central1-a \
    --keys role unique-id

Après avoir ajouté et supprimé des métadonnées d'une instance existante, vous pouvez afficher vos modifications en exécutant la commande suivante :

gcloud compute instances describe my-instance --zone us-central1-a
...
metadata:
  fingerprint: eU448B6JGQw=
  items:
  - key: build-num
    value: '4.32'
  kind: compute#metadata
...

Pour modifier les métadonnées existantes ou ajouter de nouvelles métadonnées, utilisez la commande add-metadata. Les mises à jour de métadonnées d'instance s'ajoutent les unes aux autres. Cela signifie que vous devez uniquement spécifier les clés de métadonnées que vous souhaitez ajouter ou modifier. Si vous spécifiez une clé existante, la valeur de la clé sera mise à jour avec la nouvelle valeur.

Pour les images sur lesquelles des outils Google Compute Engine sont installés, deux clés de métadonnées sont réservées pour la fonctionnalité de script de démarrage :

  • startup-script : indique le contenu du script exécuté au démarrage de l'instance. Pour un contenu de script plus long, vous pouvez utiliser l'indicateur --metadata-from-file pour transférer un chemin vers un fichier contenant le contenu du script.
  • startup-script-url : indique qu'un script à l'emplacement spécifié accessible publiquement est exécuté au démarrage de l'instance.

Par exemple, pour créer une instance nommée "my-instance" dans la zone "us-central1-a", avec le contenu du script de démarrage spécifié à l'aide de l'indicateur --metadata, vous pouvez utiliser la commande suivante :

gcloud compute instances create my-instance --zone us-central1-a \
    --metadata startup-script="echo 'hello world'"

Si vous utilisez SSH pour "my-instance" et vérifiez le journal système (/var/log/syslog), le résultat du script de démarrage s'affiche.

Avec une instance existante nommée "my-instance", vous pouvez ajouter le script de démarrage suivant à partir d'un fichier local à l'aide de l'indicateur --metadata-from-file :

gcloud compute instances add-metadata my-instance \
    --metadata-from-file startup-script=/local/path/to/script/startup

Dans cet exemple, le script de démarrage est exécuté lorsque l'instance redémarre, par exemple lorsque vous utilisez la commande gcloud compute instances reset.

Ajouter et supprimer des métadonnées au niveau du projet

Les métadonnées au niveau du projet sont accessibles par toutes les instances d'un projet. Par défaut, un projet inclut des métadonnées réservées au niveau du projet. Vous pouvez également ajouter et supprimer des métadonnées personnalisées au niveau du projet. Comme les métadonnées d'une instance, les mises à jour de métadonnées de projet s'ajoutent les unes aux autres. Cela signifie que vous devez uniquement spécifier les clés de métadonnées que vous souhaitez ajouter ou modifier. Si vous spécifiez une clé existante, la valeur de la clé sera mise à jour avec la nouvelle valeur.

Pour afficher les métadonnées au niveau du projet, utilisez la commande project-info describe :

gcloud compute project-info describe

La commande suivante ajoute deux métadonnées au niveau du projet.

gcloud compute project-info add-metadata \
    --metadata-from-file startup-script=/local/path/to/script
    --metadata startup-id=1234

Notez que la clé startup-script est réservée : cela signifie que le contenu du fichier local spécifié doit être exécuté lorsque les instances démarrent.

Pour supprimer les deux métadonnées que vous venez d'ajouter, utilisez la commande suivante :

gcloud compute project-info remove-metadata --keys startup-script startup-id

Supprimer des instances

Pour supprimer l'instance nommée "my-instance" dans la zone "us-central1-a", vous pouvez utiliser la commande instances delete :

gcloud compute instances delete my-instance --zone us-central1-a

Lorsque vous créez une instance, un disque persistant est également créé. Ce disque compte dans votre quota de disque persistant et entraîne des frais associés mensuels. Par défaut, la commande instances delete utilisée pour supprimer une instance supprime le disque persistant associé à l'instance. Pour modifier ce comportement, procédez comme suit :

  • Utilisez l'indicateur --keep-disks de la commande instances delete.
  • Configurez le disque pour qu'il ne soit pas supprimé automatiquement. Après avoir créé une instance et avant de supprimer les instances, vous pouvez à tout moment utiliser la commande instances set-disk-auto-delete pour conserver le disque persistant. Notez que l'indicateur --delete-disks de la commande instances delete supprime les disques indépendamment de la configuration de suppression automatique.

Pour plus d'informations, consultez la section relative à la définition de l'état de suppression automatique d'un disque persistant.

Répertorier les opérations

Les opérations constituent un enregistrement des modifications apportées à vos ressources Google Compute Engine. Pour obtenir la liste de toutes les opérations d'un projet, vous pouvez utiliser la commande operations list :

gcloud compute operations list

Les opérations incluent des champs d'application pouvant être utilisés pour réduire les opérations affichées dans une demande de liste. Par exemple, vous pouvez utiliser les indicateurs --global, --zones et --regions pour affiner vos résultats. La commande suivante n'affiche que les opérations des zones "us-central1-a" et "us-central1-b" :

gcloud compute operations list --filter="zone:(us-central1-a us-central1-b)"

Pour plus d'exemples sur l'obtention et l'affichage des ressources, y compris les opérations, consultez la section relative à la récupération de ressources.

Obtenir des pages d'aide

Les commandes suivantes vous montrent comment accéder à différents types d'aide, de l'aide générale sur la commande gcloud compute à une aide spécifique sur un groupe de ressources (instances) ou une commande (create). Une aide complète pour toutes les ressources et les commandes suit le modèle suivant :

gcloud compute --help
gcloud compute instances --help
gcloud compute instances create --help

Pour obtenir rapidement de l'aide, utilisez l'indicateur -h au lieu de l'indicateur --help. Vous pouvez également consulter l'aide complète sur la page de référence du SDK Cloud.

Pour obtenir une aide complète sur les commandes spécifiques à la configuration de l'outil gcloud, exécutez la commande suivante :

gcloud topic TOPIC

TOPIC est la rubrique pour laquelle vous souhaitez obtenir de l'aide. Pour obtenir une liste des rubriques pour lesquelles vous pouvez obtenir de l'aide, consultez la documentation de référence de gcloud topic.

Étapes suivantes

Vous pouvez maintenant commencer à utiliser l'outil gcloud compute. Voici quelques conseils pour commencer :

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Documentation Compute Engine