gcloud compute

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

L'outil gcloud fait partie du SDK Cloud. Cet outil de ligne de commande unifié intègre 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 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 SDK Cloud.

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

Configurer gcloud compute

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

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

  1. Exécutez gcloud init pour lancer 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), vous verrez le résultat ci-dessous. Ou, si vous travaillez sur une machine locale 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 un ordinateur distant ou utilisez l'indicateur --console-only, copiez et collez le code renvoyé sur la ligne de commande après Saisissez le code de validation :. Sinon, le code est automatiquement envoyé à l'outil de ligne de commande.

  3. Choisissez les identifiants pour cette configuration.

    Lorsque vous aurez configuré vos identifiants, gcloud vous invite à définir un projet par défaut pour cette configuration. Sélectionnez un ID de projet dans la liste.

    Après avoir défini cette propriété, toutes vos commandes gcloud compute utilisent l'ID de projet par défaut, sauf si vous le remplacez par l'indicateur --project ou la variable d'environnement CLOUDSDK_CORE_PROJECT. Si vous ne définissez pas de projet par défaut ou de 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 déduire ces informations sans que vous ayez à les fournir à chaque requête. Vous pouvez toujours remplacer ou modifier manuellement ces paramètres par défaut.

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 à utiliser pour l'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 seront utilisés pour l'authentification auprès des services Google Cloud.

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.

Pour plus d'informations sur l'utilisation des configurations, consultez la page gcloud topic 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 connaître les 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]

où [PROJECT_ID] correspond à votre ID de 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 ni 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 pour chaque requête.
  • Si une valeur par défaut est définie, gcloud utilise automatiquement la valeur par défaut pour toutes les requêtes gcloud que vous effectuez manuellement, sauf si vous remplacez 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 requête 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 les modifications de zone et de région par défaut qu'après une nouvelle exécution de la commande gcloud init. Après avoir mis à jour vos métadonnées par défaut, exécutez 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 manuellement une autre zone ou région sans mettre à jour le serveur de métadonnées, en définissant ces propriétés localement sur votre 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 totalement 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 de spécifier 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 options explicites telles 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, ajoutez ces commandes dans votre fichier ~/.bashrc, puis 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 ajoutant à vos commandes des options --zone ou --region spécifiques.

Définir des valeurs pour chaque requête

Vous pouvez remplacer les propriétés par défaut en ajoutant des indicateurs --zone ou --region spécifiques à 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 requête.

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 une option explicite --zone, --region ou --project, il remplace tous les autres paramètres pour cette seule requête.
  • Si les propriétés de zone et de région par défaut sont définies uniquement dans le serveur de métadonnées, l'outil de ligne de commande gcloud définit ces propriétés pour votre client gcloud lors de l'exécution 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'option --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. Pour afficher les valeurs par défaut, accédez à l'aide concernant la commande create command :

gcloud compute instances create --help

Répertorier les instances

Il existe plusieurs façons de répertorier 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 sur la récupération des informations sur les 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 la récupération et l'affichage des listes de ressources, y compris les instances, consultez la section sur la récupération des informations sur les ressources.

Se connecter aux instances

gcloud compute facilite la connexion à vos instances. Les commandes gcloud compute ssh et gcloud compute scp fournissent des wrappers autour de SSH et SCP, qui 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 depuis une instance vers une machine locale. 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

Par défaut, les commandes gcloud compute ssh et gcloud compute scp utilisent le fichier de clé privée "~/.ssh/google_compute_engine". Si vous ne souhaitez pas utiliser ce fichier de clé, vous pouvez en spécifier un autre en spécifiant un autre emplacement avec 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 directement ssh et scp, gcloud compute peut générer un fichier de configuration SSH contenant des alias hôtes pour vos instances avec 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 relancer 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 accéder à l'instance "my-instance" située dans la zone "us-central1-a" et associée au projet "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 "fichier-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 Stocker et récupérer des métadonnées.

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

Vous pouvez configurer les métadonnées d'instance avec gcloud compute soit à l'aide de la commande create lorsque vous créez une instance, soit à l'aide des commandes add-metadata et remove-metadata pour une instance existante. Les métadonnées sont spécifiées sous forme de paires clé-valeur séparées par un signe égal ("=") à l'aide de l'indicateur --metadata. Vous pouvez également lire les métadonnées à 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 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 qui est exécuté au démarrage de l'instance. Si le contenu du script est plus long, vous pouvez utiliser l'indicateur --metadata-from-file pour transmettre le chemin d'accès à un fichier contenant le script.
  • startup-script-url : indique qu'un script situé à l'emplacement publiquement accessible spécifié 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 script de démarrage spécifié avec l'option --metadata, vous pouvez utiliser :

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 gcloud computeinstances 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 existantes 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 et signifie que le contenu du fichier local spécifié doit être exécuté au démarrage des instances.

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. La commande instances delete de suppression d'une instance supprime par défaut le disque persistant associé à l'instance. Pour modifier ce comportement, vous pouvez au choix :

  • utiliser l'option --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 à tout moment avant de la supprimer, vous pouvez utiliser la commande instances set-disk-auto-delete pour conserver le disque persistant. Notez que l'option --delete-disks de la commande instances delete supprimera les disques, quelle que soit la configuration de la suppression automatique.

Pour plus d'informations, consultez la section sur 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 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 ont des champs d'application qui peuvent être utilisés pour affiner les opérations renvoyées dans une requête de liste. Par exemple, vous pouvez utiliser les indicateurs --global, --zones et --regions pour affiner vos résultats. La commande suivante renvoie uniquement les opérations dans les zones us-central1-a et us-central1-b :

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

Vous trouverez d'autres exemples sur l'obtention et l'affichage des ressources, y compris les opérations, dans la section sur la récupération des informations sur les ressources.

Obtenir des pages d'aide

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

gcloud compute --help

gcloud compute instances --help

gcloud compute instances create --help

Vous pouvez obtenir une aide rapide en utilisant l'option -h au lieu de l'option --help. Vous pouvez également consulter l'aide complète dans la documentation de référence du SDK Cloud.

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

gcloud topic TOPIC

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

Étapes suivantes

Vous pouvez à présent utiliser l'outil gcloud compute vous-même ! Voici quelques conseils pour commencer :