gcloud compute


L'outil de ligne de commande gcloud permet de gérer les ressources Compute Engine à l'aide du groupe de commandes gcloud compute. gcloud compute est une alternative à l'utilisation de 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 associée à la ligne de commande, 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 le guide de démarrage rapide pour Linux ou le guide de démarrage rapide pour Windows.

Avant de commencer

  • Si vous souhaitez exécuter gcloud compute dans une invite de commande, installez, mettez à jour et initialisez le SDK Cloud.
  • Si vous n'avez pas d'invite de commande à votre disposition, essayez d'utiliser gcloud compute dans Cloud Shell. Cloud Shell est automatiquement installé, mis à jour et initialisé avec la dernière version du SDK Cloud.

Utiliser les configurations

L'outil 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 et le paramètre de zone par défaut. L'outil 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.

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 à l'aide de l'outil de ligne de commande gcloud afin d'obtenir et d'utiliser les informations du projet.

Afficher les propriétés par défaut

Pour connaître vos propriétés par défaut, exécutez la commande suivante à l'aide de l'outil de ligne de commande gcloud. Remplacez PROJECT_ID par l'ID du projet.

gcloud compute project-info describe --project PROJECT_ID

Afficher la région et la zone par défaut

Pour connaître vos paramètres de région et de zone par défaut, exécutez les commandes suivantes :

gcloud config get-value compute/zone
gcloud config get-value compute/region

Si les réponses google-compute-default-region ou google-compute-default-zone renvoyées sont (unset), 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, l'outil gcloud vous invite à saisir une région et une zone pour chaque requête.

  • Si une valeur par défaut est définie, l'outil gcloud utilise automatiquement la valeur par défaut pour toutes les requêtes de l'outil gcloud, sauf si vous remplacez 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

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.

Définissez les régions et les zones par défaut à l'aide des commandes suivantes :

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

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, l'outil gcloud vous 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 options explicites telles que --zone ou --region.

Linux/macOS
Exécutez la commande export pour définir les variables de projet, de zone et de région.
export CLOUDSDK_CORE_PROJECT=PROJECT
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
Exécutez la commande set pour définir les variables de projet, de zone et de région.
C:\> set CLOUDSDK_CORE_PROJECT=PROJECT
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 de cette requête uniquement.
  • 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 gcloud vous invite à saisir 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 gcloud 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 le serveur de métadonnées, le client local et les variables d'environnement, l'outil gcloud 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, l'outil 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 à des 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 :

<pre class="devsite-click-to-copy>gcloud topic <var>TOPIC</var></pre>

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