Stocker et récupérer les métadonnées d'instance

Chaque instance stocke ses métadonnées sur un serveur de métadonnées. Vous pouvez interroger ce serveur, de manière automatisée, depuis l'instance et depuis l'API Compute Engine afin d'obtenir des informations sur l'instance, telles que le nom d'hôte de l'instance, l'ID d'instance, les scripts de démarrage et d'arrêt, les métadonnées personnalisées et les informations de compte de service. Votre instance a automatiquement accès à l'API du serveur de métadonnées sans aucune autorisation supplémentaire.

Le serveur de métadonnées est particulièrement intéressant lorsqu'il est utilisé en combinaison avec des scripts de démarrage et d'arrêt. En effet, il vous permet d'obtenir des informations uniques sur une instance de manière automatisée, sans autorisation supplémentaire. Par exemple, vous pouvez écrire un script de démarrage qui récupère la paire clé/valeur de métadonnées pour l'adresse IP externe d'une instance et vous servir de cette adresse IP dans votre script pour configurer une base de données. Les clés de métadonnées par défaut étant les mêmes sur chaque instance, vous pouvez réutiliser votre script sans avoir à le mettre à jour pour chaque instance. Cela vous permet de créer un code moins fragile pour vos applications.

Les métadonnées sont stockées au format key:value. Il existe un ensemble d'entrées de métadonnées par défaut auquel chaque instance a accès. Vous pouvez également définir des métadonnées personnalisées.

Pour accéder au serveur de métadonnées, vous pouvez interroger l'URL des métadonnées.

Version actuelle : v1

Compute Engine peut offrir plusieurs versions de métadonnées à la fois. Toutefois, nous vous recommandons de toujours utiliser la version la plus récente du serveur de métadonnées disponible. À tout moment, Google Compute Engine peut ajouter de nouvelles entrées au serveur de métadonnées, ainsi que de nouveaux champs aux réponses. Consultez régulièrement cette page pour savoir si des modifications ont été apportées.

Avant de commencer

• Si vous souhaitez utiliser les exemples de lignes de commande de ce guide, procédez comme suit :
  1. Installez la dernière version de l'outil de ligne de commande gcloud ou appliquez la mise à jour correspondante.
  2. Définissez une région et une zone par défaut.
• Si vous voulez utiliser les exemples d'API de ce guide, configurez l'accès aux API.

Autorisations requises pour cette tâche

Pour effectuer cette tâche, vous devez disposer des autorisations suivantes :

• compute.instances.setMetadata sur l'instance si vous y définissez des métadonnées.
• compute.projects.setCommonInstanceMetadata sur le projet si vous définissez des métadonnées à l'échelle du projet.
• compute.projects.get sur le projet si vous souhaitez uniquement obtenir les métadonnées.
• compute.instances.get sur l'instance si vous souhaitez uniquement obtenir les métadonnées.

Métadonnées du projet et de l'instance

Les métadonnées peuvent être attribuées au niveau du projet et de l'instance. Les métadonnées au niveau du projet se propagent sur toutes les instances de machine virtuelle (VM) du projet, tandis que les métadonnées au niveau de l'instance n'affectent que cette instance.

Clés de métadonnées par défaut

Google Compute Engine définit un ensemble d'entrées de métadonnées par défaut qui fournissent des informations sur votre instance ou projet. Les métadonnées par défaut sont toujours définies et configurées par le serveur. Vous ne pouvez pas modifier manuellement ces paires de métadonnées.

Vous trouverez ci-dessous une liste des métadonnées par défaut disponibles pour un projet. Certaines entrées de métadonnées correspondent à des répertoires contenant d'autres clés de métadonnées. Cette différence est indiquée à l'aide d'une barre oblique dans le nom des métadonnées. Par exemple, attributes/ correspond à un répertoire contenant d'autres clés, alors que numeric-project-id correspond à une clé de métadonnées mappée sur une valeur.

Élément concerné : http://metadata.google.internal/computeMetadata/v1/project/
Entrée de métadonnées	Description
attributes/	Répertoire des valeurs de métadonnées personnalisées définies pour ce projet.
attributes/disable-legacy-endpoints	Désactive les anciens points de terminaison du serveur de métadonnées pour toutes les instances de votre projet. Définissez toujours disable-legacy-endpoints=TRUE, à moins que le projet utilise d'anciens points de terminaison. Mettez à jour vos applications afin qu'elles utilisent des points de terminaison v1.
attributes/enable-oslogin	Active la fonctionnalité de gestion des clés SSH de connexion au système d'exploitation sur votre projet lorsque vous définissez enable-oslogin=TRUE.
attributes/vmdnssetting	Configure le format des noms DNS internes pour les instances de votre projet. Pour en savoir plus sur les noms DNS internes, consultez la section Configurer des noms DNS.
attributes/ssh-keys	Si votre projet et vos instances ne sont pas configurés pour gérer les clés SSH à l'aide de la connexion au système d'exploitation, cet attribut vous permet de configurer des clés SSH publiques pouvant se connecter aux instances de ce projet. S'il existe plusieurs clés SSH, chaque clé est séparée par un caractère de retour à la ligne (\n). Cette valeur est une chaîne. Les clés SSH gérées par la connexion à l'OS ne sont pas visibles dans cette valeur de métadonnées. Exemple : "user1:ssh-rsa mypublickey [e-mail]\nuser2:ssh-rsa mypublickey [e-mail]"
numeric-project-id	ID numérique du projet (numéro du projet) de l'instance, à ne pas confondre avec le nom du projet visible dans la console Google Cloud Platform. Cette valeur est différente de la valeur d'entrée de métadonnées project-id.
project-id	ID du projet.

Voici une liste de métadonnées par défaut pour une instance :

Élément concerné : http://metadata.google.internal/computeMetadata/v1/instance/
Entrée de métadonnées	Description
attributes/	Répertoire des valeurs de métadonnées personnalisées transmises à l'instance lors du démarrage ou de l'arrêt. Consultez la section sur la spécification des métadonnées personnalisées ci-dessous.
attributes/enable-oslogin	Active la fonctionnalité de gestion des clés SSH de connexion au système d'exploitation sur cette instance lorsque vous définissez enable-oslogin=TRUE.
attributes/vmdnssetting	Configure le format des noms DNS internes pour cette instance. Pour en savoir plus sur les noms DNS internes, consultez la section Configurer des noms DNS.
attributes/ssh-keys	Si votre instance n'est pas configurée pour gérer les clés SSH à l'aide de la connexion au système d'exploitation, cet attribut vous permet de configurer des clés SSH publiques pouvant se connecter à cette instance. S'il existe plusieurs clés SSH, chaque clé est séparée par un caractère de retour à la ligne (\n). Cette valeur est une chaîne. Les clés SSH gérées par la connexion à l'OS ne sont pas visibles dans cette valeur de métadonnées. Exemple : "user1:ssh-rsa mypublickey [e-mail]\nuser2:ssh-rsa mypublickey [e-mail]"
cpu-platform	Plate-forme du processeur de l'instance.
description	Description en texte libre d'une instance attribuée à l'aide du paramètre --description ou définie dans l'API.
disks/	Répertoire de disques associés à cette instance.
guest-attributes/	Valeurs de métadonnées d'instances personnalisées que vous pouvez utiliser pour publier des notifications d'état peu fréquentes, des données de faible volume ou des données de basse fréquence. Ces valeurs sont utiles pour indiquer la fin des scripts de démarrage ou pour fournir d’autres notifications d’état peu fréquentes à d’autres applications. Tout utilisateur ou processus de votre instance de VM peut lire et écrire dans les espaces de noms et les clés des métadonnées "guest-attributs".
hostname	Nom d'hôte de l'instance.
id	ID de l'instance. Il s'agit d'un identifiant numérique unique généré par Google Compute Engine. Cette valeur est utile pour identifier les instances si vous ne souhaitez pas utiliser leurs noms.
machine-type	Valeur de métadonnées pour le type de machine de cette instance au format suivant : projects/[NUMERIC_PROJECT_ID]/machineTypes/[MACHINE_TYPE]
name	Nom de l'instance.
network-interfaces/	Répertoire des interfaces réseau de l'instance.
network-interfaces/<index>/forwarded-ips/	Répertoire de toutes les adresses IP externes pointant actuellement vers cette instance de machine virtuelle pour l'interface réseau sur <index>. En particulier, cette valeur fournit une liste d'adresses IP externes diffusées par les règles de transfert qui dirigent les paquets vers cette instance.
scheduling/	Répertoire avec les options de planification pour l'instance.
scheduling/on-host-maintenance	Paramètre de comportement de l'événement de maintenance transparente de l'instance. Cette valeur est définie avec l'indicateur --on_host_maintenance ou via l'API.
scheduling/automatic-restart	Paramètre de redémarrage automatique de l'instance. Cette valeur est définie avec l'indicateur ‑‑automatic_restart ou via l'API.
scheduling/preemptible	Paramètre préemptif de l'instance. Si cette valeur est définie sur TRUE, l'instance est préemptive. Cette valeur est définie lorsque vous créez une instance, et elle ne peut pas être modifiée.
maintenance-event	Chemin d'accès qui indique qu'un événement de maintenance transparente affecte cette instance. Consultez la section relative aux notifications de maintenance transparente pour plus de détails.
service-accounts/	Répertoire des comptes de service associés à l'instance.
service-accounts/<service-account-name>/identity	Jeton Web JSON unique à l'instance. Vous devez inclure le paramètre "audience" dans votre requête pour cette valeur de métadonnées d'instance. Exemple : "?audience=http://www.example.com". Consultez la page Valider l'identité des instances pour savoir comment demander et valider des jetons d'identité d'instance.
tags	Tous les tags associés à l'instance.
zone	Valeur de métadonnées pour la zone où cette instance est exécutée. Cette valeur a le format suivant : projects/[NUMERIC_PROJECT_ID]/zones/[ZONE].

Obtenir des métadonnées

Vous pouvez interroger le contenu du serveur de métadonnées en envoyant une requête aux URL racine suivantes à partir d'une instance de VM. Envoyez des requêtes au serveur de métadonnées à l'aide de l'URL http://metadata.google.internal/computeMetadata/v1/.

Toutes les valeurs de métadonnées sont définies comme des sous-chemins d'accès situés sous ces URL racine.

Vous pouvez interroger des valeurs de métadonnées par défaut uniquement à partir de l'instance associée. Vous ne pouvez pas interroger les métadonnées par défaut d'une instance à partir d'une autre instance ou directement sur votre ordinateur local. Vous pouvez utiliser des outils standards tels que curl ou wget depuis l'instance vers son serveur de métadonnées.

Lorsque vous interrogez des métadonnées, vous devez fournir l'en-tête suivant dans toutes vos requêtes :

Metadata-Flavor: Google

Cet en-tête indique que la requête a été envoyée avec l'intention de récupérer des valeurs de métadonnées, et non involontairement à partir d'une source non sécurisée. De plus, il permet au serveur de métadonnées de renvoyer les données demandées. Si vous ne fournissez pas cet en-tête, le serveur de métadonnées refuse votre requête.

Remarque : Auparavant, l'en-tête X-Google-Metadata-Request: True était requis dans les requêtes. Ces deux en-têtes sont toujours acceptés, mais il est recommandé d'utiliser l'en-tête Metadata-Flavor plutôt que X-Google-Metadata-Request: True.

En-tête "X-Forwarded-For"

Toutes les requêtes contenant l'en-tête X-Forwarded-For sont automatiquement refusées par le serveur de métadonnées. Cet en-tête indique généralement que la requête a été exécutée par un serveur proxy et peut ne pas être une requête effectuée par un utilisateur autorisé. Pour des raisons de sécurité, toutes ces requêtes sont refusées.

Limites

Lorsque vous exécutez la commande curl pour récupérer les métadonnées du serveur, notez que certains caractères encodés ne sont pas disponibles dans le chemin de la requête. Les caractères encodés ne sont acceptés que dans le chemin de la requête.

Par exemple, la requête suivante est susceptible de ne pas aboutir :

http://metadata.goog/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

Pour que cette requête fonctionne, vous devez remplacer le caractère encodé non disponible dans le chemin de la requête (%40) par la valeur acceptée équivalente (@).

http://metadata.goog/computeMetadata/v1/instance/[e-mail]/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true

Le tableau suivant récapitule les caractères encodés qui ne sont pas acceptés dans le chemin d'une requête.

Caractère encodé	Valeur acceptée
%21	!
%24	$
%27	'
%28	(
%29	)
%2A	*
%2C	,
%40	@

Les métadonnées sont-elles sécurisées ?

Lorsque vous effectuez une requête pour obtenir des informations auprès du serveur de métadonnées, votre requête et la réponse de métadonnées qui s'en suit ne quittent jamais l'hôte physique exécutant l'instance de VM.

Interroger les listes de répertoires

Le serveur de métadonnées organise certaines clés de métadonnées à l'aide de répertoires. Toute entrée de métadonnées se terminant par une barre oblique correspond à un répertoire. Par exemple, l'entrée disks/ désigne un répertoire de disques associé à cette instance :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"

0/
1/
2/

De même, si vous souhaitez plus d'informations sur le répertoire du disque 0/, vous pouvez interroger l'URL spécifique de ce répertoire:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/" -H "Metadata-Flavor: Google"

device-name
index
mode
type

Interroger les points de terminaison

Si une clé de métadonnées n'est pas un répertoire, il s'agit d'un point de terminaison qui renvoie une ou plusieurs valeurs. Par exemple, pour interroger le mode d'un disque spécifique, interrogez le point de terminaison suivant :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/mode" -H "Metadata-Flavor: Google"

READ_WRITE

Par défaut, chaque point de terminaison a un format prédéfini pour la réponse. Certains points de terminaison peuvent renvoyer des données au format JSON par défaut, tandis que d'autres peuvent renvoyer des données sous forme de chaîne. Vous pouvez remplacer la spécification de format de données par défaut à l'aide des paramètres de requête alt=json ou alt=text. Ces paramètres renvoient respectivement les données au format de chaîne JSON ou sous forme de représentation en texte brut.

Par exemple, la clé tags renvoie automatiquement les données au format JSON. Spécifiez le paramètre de requête alt=text pour renvoyer des données au format texte :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"

["bread","butter","cheese","cream","lettuce"]

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"

bread
butter
cheese
cream
lettuce

Interroger les métadonnées de manière récursive

Si vous souhaitez renvoyer tout le contenu sous un répertoire, utilisez le paramètre recursive=true avec votre requête :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"

[{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]

Par défaut, les contenus récursifs sont renvoyés au format JSON. Si vous voulez renvoyer le contenu au format texte, ajoutez le paramètre alt=text :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"

0/device-name boot
0/index 0
0/mode READ_WRITE
0/type PERSISTENT
1/device-name persistent-disk-1
1/index 1
1/mode READ_WRITE
1/type PERSISTENT
2/device-name persistent-disk-1
2/index 2
2/mode READ_ONLY
2/type PERSISTENT

Définir des métadonnées personnalisées

Vous pouvez définir des métadonnées personnalisées pour une instance ou un projet à partir de la console Google Cloud Platform, de l'outil de ligne de commande gcloud ou de l'API Compute Engine. Les métadonnées personnalisées sont utiles pour transmettre des valeurs arbitraires à votre projet ou à votre instance, ainsi que pour définir des scripts de démarrage et d'arrêt.

Limites relatives à la taille des métadonnées personnalisées

Google Compute Engine applique les limites suivantes à la taille des valeurs de métadonnées personnalisées :

• 256 Ko pour chaque entrée de métadonnées individuelle
• Total cumulé de 512 Ko pour toutes les entrées de métadonnées par instance

En particulier, les clés SSH sont stockées en tant que métadonnées personnalisées sous la clé ssh-keys. Si le contenu de métadonnées pour cette clé dépasse la limite de 256 Ko, vous ne pourrez pas ajouter de clés SSH. Si vous atteignez cette limite, envisagez de supprimer les clés inutilisées afin de libérer de l'espace de métadonnées pour les nouvelles clés.

Le contenu des scripts de démarrage et d'arrêt peut également être stocké en tant que métadonnées personnalisées. Il est pris en compte dans ces limites de taille si vous fournissez directement le contenu des scripts de démarrage ou d'arrêt. Pour éviter cette situation, stockez le script de démarrage ou d'arrêt en tant que fichier hébergé sur un emplacement externe, tel que Google Cloud Storage, puis fournissez l'URL du script de démarrage lors de la création d'une instance. Ces fichiers seront téléchargés sur l'instance de VM au lieu d'être stockés sur le serveur de métadonnées.

Définir des métadonnées d'instance

Définissez les métadonnées personnalisées d'une instance à l'aide de la console GCP, de l'outil gcloud ou de l'API. Les métadonnées d'instance s'appliquent uniquement à une instance spécifique.

Définir des métadonnées lors de la création de l'instance

Console

1. Dans la console GCP, accédez à la page "Instances de VM".

   Accéder à la page Instances de VM

2. Cliquez sur Créer une instance.
3. Sur la page Créer une instance, spécifiez les propriétés souhaitées pour votre instance.
4. Dans la section Métadonnées, indiquez autant de paires clé/valeur associées aux métadonnées personnalisées que nécessaire.
5. Cliquez sur Créer pour créer l'instance.

gcloud

À l'aide de l'outil de ligne de commande gcloud, ajoutez le paramètre --metadata pour définir des métadonnées personnalisées.

gcloud compute instances create example-instance --metadata foo=bar

API

Dans l'API, indiquez les métadonnées personnalisées dans la propriété de métadonnées de votre requête :

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{
  "...
        }
      ]
    }
  ],
  "metadata": {
    "items": [
      {
       "key": "foo",
       "value": "bar"
      }
    ]
  },
  ..
}

Mettre à jour des métadonnées sur une instance en cours d'exécution

Console

1. Accédez à la page Instances de VM.
2. Cliquez sur l'instance pour laquelle vous souhaitez mettre à jour les métadonnées.
3. Cliquez sur le bouton Modifier en haut de la page.
4. Sous Métadonnées personnalisées, cliquez sur Ajouter un élément ou modifiez les entrées de métadonnées existantes.
5. Enregistrez les modifications.

gcloud

Les mises à jour des métadonnées d'instance avec l'outil gcloud s'ajoutent les unes aux autres. Spécifiez uniquement les clés de métadonnées que vous souhaitez ajouter ou modifier. Si une clé que vous avez fournie existe déjà, cette clé est mise à jour avec la nouvelle valeur.

À l'aide de l'outil de ligne de commande gcloud, exécutez la commande instances add-metadata :

gcloud compute instances add-metadata INSTANCE \
  --metadata bread=mayo,cheese=cheddar,lettuce=romaine

Si vous souhaitez remplacer l'entrée lettuce=romaine par lettuce=green, exécutez la commande suivante :

gcloud compute instances add-metadata INSTANCE --metadata lettuce=green

Si vous voulez supprimer l'entrée lettuce=romaine, spécifiez la clé existante et excluez la valeur.

gcloud compute instances remove-metadata INSTANCE --keys lettuce

API

Dans l'API, envoyez une requête à la méthode instances().setMetadata. Fournissez une liste des nouvelles valeurs de métadonnées et la valeur d'empreinte fingerprint actuelle.

Une empreinte est une chaîne aléatoire de caractères générée par Compute Engine et utilisée pour effectuer un verrouillage optimal. Fournissez la valeur d'empreinte correspondante pour envoyer votre requête. L'empreinte change après chaque requête et si vous fournissez une empreinte non concordante, votre requête est refusée. De cette manière, une seule mise à jour peut être effectuée à la fois, évitant ainsi les conflits.

Pour obtenir l'empreinte actuelle d'une instance et afficher les paires clé/valeur existantes pour l'instance, envoyez une requête instances().get :

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

{
 ...
 "name": "example-instance",
 "metadata": {
  "kind": "compute#metadata",
  "fingerprint": "zhma6O1w2l8="
  "items": [
   {
    "key": "foo",
    "value": "bar"
   }
  ]
 },
 ...
}

Envoyez ensuite une requête à la méthode instances().setMetadata, puis définissez les paires clé/valeur des métadonnées personnalisées. Si l'instance possède des paires clé/valeur existantes que vous souhaitez conserver, vous devez les inclure dans la requête avec les nouvelles paires clé/valeur :

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{
 "fingerprint": "zhma6O1w2l8=",
 "items": [
  {
   "key": "foo",
   "value": "bar"
  },
  {
   "key": "baz",
   "value": "bat"
  }
 ]
}

Pour supprimer toutes les paires clé/valeur des métadonnées d'une instance, spécifiez une requête instances().setMetadata et excluez la propriété items. Sachez que vous devez toujours inclure la propriété d'empreinte de métadonnées actuelle pour que la requête aboutisse :

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{
 "fingerprint": "5rC_DXxBUZw="
}

Définir des métadonnées personnalisées à l'échelle du projet

Définissez des métadonnées à l'échelle du projet pour les appliquer à toutes les instances du projet. Par exemple, si vous définissez une paire de métadonnées baz=bat à l'échelle du projet, cette paire est automatiquement appliquée à toutes les instances du projet.

Console

1. Accédez à la page Métadonnées.
2. Cliquez sur Modifier.
3. Ajoutez ou modifiez une entrée de métadonnées.
4. Enregistrez les modifications.

gcloud

À l'aide de l'outil de ligne de commande gcloud, exécutez la commande project-info add-metadata. Exemple :

gcloud compute project-info add-metadata --metadata foo=bar,baz=bat

Affichez les métadonnées à l'aide de la commande describe :

gcloud compute project-info describe

Par exemple, vous pouvez obtenir une réponse semblable à ce qui suit :

...
commonInstanceMetadata:
  fingerprint: RfOFY_-eS64=
  items:
  - key: baz
    value: bat
  - key: foo
    value: bar
  - key: ssh-keys
...

Une paire clé/valeur de métadonnées est spécifiée avec un signe égal (key=value, par exemple). Plusieurs paires clé/valeur sont séparées par des espaces.

Vous pouvez éventuellement spécifier un ou plusieurs fichiers à partir desquels lire les métadonnées à l'aide du paramètre --metadata-from-file. Vous avez la possibilité de supprimer les valeurs de métadonnées avec la commande project-info remove-metadata.

API

Dans l'API, envoyez une requête à la méthode projects().setCommonInstanceMetadata en fournissant toutes les nouvelles valeurs de métadonnées, ainsi qu'une valeur fingerprint.

Une empreinte est une chaîne aléatoire de caractères générée par Compute Engine et utilisée pour effectuer un verrouillage optimal. Fournissez la valeur d'empreinte correspondante pour envoyer votre requête. L'empreinte change après chaque requête et si vous fournissez une empreinte non concordante, votre requête est refusée. De cette manière, une seule mise à jour peut être effectuée à la fois, évitant ainsi les conflits.

Pour obtenir l'empreinte actuelle d'une instance, effectuez une requête project().get et copiez la valeur de l'empreinte :

GET https://www.googleapis.com/compute/v1/projects/myproject

{
 "name": "myproject",
 "commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "FikclA7UBC0=",
  ...
}

Envoyez ensuite une requête à la méthode projects().setCommonInstanceMetadata et définissez les paires clé/valeur des métadonnées personnalisées :

POST https://www.googleapis.com/compute/v1/projects/myproject/setCommonInstanceMetadata

{
 "fingerprint": "FikclA7UBC0=",
 "items": [
  {
   "key": "foo",
   "value": "bar"
  }
 ]
}

Interroger les métadonnées personnalisées

Vous pouvez interroger les métadonnées personnalisées d'instance ou de projet via la console GCP, l'outil de ligne de commande gcloud ou l'API.

Console

Pour afficher les métadonnées personnalisées à l'échelle du projet, accédez à la page Métadonnées.

Pour voir les métadonnées personnalisées d'une instance, procédez comme suit :

1. Accédez à la page Instances de VM.
2. Cliquez sur l'instance pour laquelle vous souhaitez afficher les métadonnées.
3. Sous Métadonnées personnalisées, affichez les métadonnées personnalisées de l'instance.

gcloud

Interrogez les métadonnées à l'échelle du projet :

gcloud compute project-info describe --flatten="commonInstanceMetadata[]"

Interrogez les métadonnées de l'instance :

gcloud compute instances describe example-instance --flatten="metadata[]"

L'indicateur --flatten peut être utilisé pour définir le champ d'application de la sortie sur une clé de métadonnées appropriée. Prenons l'exemple d'une instance ayant une paire clé/valeur de métadonnées personnalisées foo:bar.

$ gcloud compute instances describe example-instance

...
metadata:
  fingerprint: Cad2L9eKNR0=
  items:
  - key: foo
    value: bar
  kind: compute#metadata
...

Pour interroger la valeur de la clé (foo), exécutez la commande suivante :

$ gcloud compute instances describe example-instance --flatten="metadata[foo]"

---
  bar

API

Pour interroger les métadonnées d'un projet, envoyez une requête vide à la méthode projects().get :

GET https://www.googleapis.com/compute/v1/projects/myproject

Pour interroger les métadonnées d'une instance, envoyez une requête vide à la méthode instance().get :

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

Définir et interroger des attributs d'invité

Les attributs d'invité sont un type spécifique de métadonnées personnalisées auxquelles vos applications peuvent accéder en écriture alors qu'elles sont en cours d'exécution sur votre instance. N'importe quelle application ou n'importe quel utilisateur de votre instance peut lire et écrire des données dans ces valeurs de métadonnées des attributs d'invité.

Cas d'utilisation des attributs d'invité

Utilisez les attributs d'invité uniquement pour les cas d'utilisation nécessitant de petites quantités de données qui ne changent pas souvent. Les meilleurs cas d'utilisation pour les attributs d'invité sont les suivants :

• Le nombre de requêtes est limité à 10 requêtes par minute et par instance de VM.
• Les requêtes ne dépassent pas un nombre de 3 requêtes par seconde. Si ce nombre maximal est dépassé, Compute Engine peut supprimer de manière arbitraire les attributs d'invité en cours d'écriture. Cette suppression de données est nécessaire pour garantir que d'autres données système essentielles puissent être écrites sur le serveur.

Les attributs d'invité fonctionnent bien pour les situations dans lesquelles vous devez publier des données peu volumineuses et de manière peu fréquente. Par exemple, les attributs d'invité fonctionnent bien pour les cas d'utilisation suivants :

• Les scripts de démarrage peuvent signaler l'initialisation réussie en définissant une valeur d'état personnalisée dans les attributs d'invité.
• Les agents de gestion de la configuration peuvent publier un nom de système d'exploitation invité et une version dans les attributs d'invité.
• L'agent de gestion de l'inventaire peut publier la liste des packages installés dans la VM dans les attributs d'invité.
• Les logiciels d'orchestration de charge de travail peuvent signaler l'achèvement d'une opération dans l'invité au plan de contrôle du logiciel en définissant une valeur d'état personnalisée dans les attributs de d'invité.

Les attributs d’invité ne remplacent pas la diffusion en continu d’événements, Cloud Pub/Sub ou d’autres formes de stockage de données et de référentiels de configuration.

Remarque : Toute application ou tout utilisateur de votre instance peut à la fois lire et écrire des données dans ces valeurs de métadonnées des attributs d'invité. Les attributs d'invité ne sont pas conçus pour les cas d'utilisation qui requièrent une application invitée et une authentification ou autorisation de l'utilisateur. Par exemple, n'y stockez pas de clés ni d'autres données sensibles qui ne doivent pas être disponibles pour toutes les applications de l'invité.

Pour les lectures et les écritures depuis une instance, le serveur de métadonnées fournit une authentification et une autorisation automatiques au niveau de l'instance. Chaque instance peut lire ou écrire uniquement sur son propre serveur de métadonnées. D'autres instances ne peuvent pas accéder au serveur de métadonnées d'une autre instance. Les utilisateurs et les comptes de service ne peuvent lire les attributs d'invité d'une instance en dehors de l'instance que s'ils possèdent un rôle IAM qui fournit l'autorisation compute.instances.getGuestAttributes.

Activer les attributs d'invité sur votre instance

Par défaut, les attributs d'invité sont désactivés. Pour activer les attributs d'invité, définissez les valeurs de métadonnées nécessaires sur vos instances individuelles ou dans des métadonnées à l'échelle du projet :

Console

Définissez enable-guest-attributes dans les métadonnées d'instance lorsque vous créez une instance :

1. Dans la console GCP, accédez à la page "Instances de VM".

   Accéder à la page "Instances de VM"

2. Cliquez sur Créer une instance.
3. Sur la page Créer une instance, spécifiez les propriétés souhaitées pour votre instance.
4. Dans la section Métadonnées, ajoutez une entrée de métadonnées dans laquelle la clé est enable-guest-attributes et la valeur TRUE.
5. Cliquez sur Créer pour créer l'instance.

Définissez enable-guest-attributes dans les métadonnées à l'échelle du projet afin que ce paramètre s'applique à toutes les instances de votre projet :

1. Accédez à la page Métadonnées.
2. Cliquez sur Modifier.
3. Ajoutez une entrée de métadonnées dans laquelle la clé est enable-guest-attributes et la valeur TRUE. Vous pouvez également définir la valeur sur FALSE pour désactiver la fonctionnalité.
4. Cliquez sur Enregistrer pour appliquer les modifications.

Définissez enable-guest-attributes dans les métadonnées d'une instance existante :

1. Accédez à la page Instances de VM.
2. Cliquez sur le nom de l'instance sur laquelle vous souhaitez définir la valeur de métadonnées.
3. En haut de la page des détails de l'instance, cliquez sur Modifier pour modifier les paramètres de l'instance.
4. Sous Métadonnées personnalisées, ajoutez une entrée de métadonnées dans laquelle la clé est enable-guest-attributes et la valeur TRUE. Vous pouvez également définir la valeur sur FALSE pour exclure l'instance de la fonctionnalité.
5. En bas de la page des détails de l'instance, cliquez sur Enregistrer pour appliquer vos modifications à l'instance.

gcloud

Définissez enable-oslogin-2fa dans les métadonnées d'instance lorsque vous créez une instance :

Exécutez la commande gcloud compute instances create dans l'outil de ligne de commande gcloud et définissez enable-guest-attributes=TRUE pour activer les attributs d'invité :

gcloud compute instances create [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

Définissez enable-guest-attributes dans les métadonnées à l'échelle du projet afin que ce paramètre s'applique à toutes les instances de votre projet :

Exécutez la commande project-info add-metadata dans l'outil de ligne de commande gcloud et définissez enable-guest-attributes=TRUE pour activer les attributs d'invité :

gcloud compute project-info add-metadata --metadata enable-guest-attributes=TRUE

Vous pouvez également définir enable-guest-attributes sur FALSE pour désactiver les attributs d'invité.

Définissez enable-guest-attributes dans les métadonnées d'une instance existante :

Exécutez la commande instances add-metadata dans l'outil de ligne de commande gcloud et définissez enable-guest-attributes=TRUE pour activer les attributs d'invité :

gcloud compute instances add-metadata [INSTANCE_NAME] --metadata enable-guest-attributes=TRUE

Vous pouvez également définir enable-guest-attributes sur FALSE pour exclure l'utilisation d'attributs d'invité pour votre instance.

Définir les attributs d'invité

Tout processus s'exécutant dans la VM peut écrire dans les valeurs des attributs d'invité, y compris les scripts et les applications qui n'ont pas sudo ou de droits d'administrateur. Les utilisateurs ou les comptes de service extérieurs à l'instance ne peuvent pas écrire sur les valeurs de métadonnées des attributs d'invité.

Par exemple, vous pouvez utiliser une requête curl à partir de votre instance pour écrire une valeur dans le chemin d'accès des métadonnées des guest-attributes :

curl -X PUT --data "[VALUE]" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/[NAMESPACE]/[KEY] -H "Metadata-Flavor: Google"

où :

• [NAMESPACE] est un groupe logique pour votre [KEY]. Les attributs d'invité doivent avoir un espace de noms.
• [VALUE] correspond à la valeur que vous souhaitez écrire.
• [KEY] correspond au chemin d'accès dans guest-attributes où la valeur est stockée.

Obtenir les attributs d'invité

Les utilisateurs ou les comptes de service peuvent lire les attributs d'invité s'ils possèdent un rôle IAM qui fournit l'autorisation compute.instances.getGuestAttributes. N'importe quel utilisateur ou application de l'instance peut également lire les valeurs de métadonnées pour cette instance spécifique.

Tout processus s'exécutant dans la VM peut écrire dans les valeurs des attributs d'invité, y compris les scripts et les applications qui ne possèdent pas sudo ou de droits d'administrateur. Par exemple, vous pouvez utiliser une requête curl à partir de votre instance pour lire une valeur à partir du chemin d'accès des métadonnées des guest-attributes :

curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/[NAMESPACE]/[KEY] -H "Metadata-Flavor: Google"

où [KEY] est le chemin d'accès dans guest-attributes à partir duquel vous voulez lire la valeur de métadonnées.

Vous pouvez également afficher toutes les valeurs d'attribut d'invité en une seule requête :

curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/[NAMESPACE]/ -H "Metadata-Flavor: Google"

où :

• [NAMESPACE] est un groupe logique pour votre [KEY]. Les attributs d'invité doivent avoir un espace de noms.

• [KEY] correspond au chemin d'accès dans guest-attributes où la valeur est stockée.

gcloud

Utilisez l'outil de ligne de commande gcloud pour lire les valeurs de métadonnées d'attribut d'invité à partir d'une instance. Par exemple, vous pouvez récupérer toutes les valeurs de l'instance :

gcloud compute instances get-guest-attributes [INSTANCE_NAME] --zone [ZONE]

Pour récupérer toutes les valeurs sous un espace de noms spécifique, incluez l'indicateur --query-path et l'espace de noms que vous avez défini :

gcloud compute instances get-guest-attributes [INSTANCE_NAME] --query-path=[NAMESPACE]/ --zone [ZONE]

Pour récupérer toutes les valeurs sous un espace de noms spécifique, incluez l'indicateur --query-path, l'espace de noms et la clé de la valeur que vous avez définie :

gcloud compute instances get-guest-attributes [INSTANCE_NAME] --query-path=[NAMESPACE]/[KEY] --zone [ZONE]

où :

• [INSTANCE_NAME] est le nom de l'instance à partir de laquelle vous souhaitez lire la valeur de métadonnées de l'attribut d'invité.
• [KEY] est le chemin d'accès dans les métadonnées de guest-attributes où la valeur est stockée.
• [ZONE] est la zone où se trouve l'instance.

API

Utilisez la méthode API compute.instances.getguestattributes :

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]/[KEY]

où :

• [PROJECT_ID] est l'ID de votre projet.
• [ZONE] est la zone où se situe votre instance.
• [INSTANCE_NAME] est le nom de l'instance à partir de laquelle vous souhaitez lire la valeur de métadonnées de l'attribut d'invité.
• [KEY] est le chemin d'accès dans les métadonnées de guest-attributes où la valeur est stockée.

Pour récupérer toutes les clés d’un [NAMESPACE], omettez la [KEY] :

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]

Pour récupérer toutes les clés de chaque espace de noms sur l'instance, omettez les éléments [NAMESPACE] et queryPath :

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes

Si vous disposez d'un jeton OAuth, vous pouvez également utiliser curl :

curl -H "Authorization: Bearer [OAUTH_TOKEN]" https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]/getGuestAttributes?queryPath=[NAMESPACE]/[KEY]

où :

• [OAUTH_TOKEN] est votre jeton OAuth.
• [PROJECT_ID] est l'ID de votre projet.
• [ZONE] est la zone où se situe votre instance.
• [INSTANCE_NAME] est le nom de l'instance à partir de laquelle vous souhaitez lire la valeur de métadonnées de l'attribut d'invité.
• [NAMESPACE] est un groupe logique pour votre [KEY]. Les attributs d'invité doivent avoir un espace de noms.
• [KEY] est le chemin d'accès dans les métadonnées de guest-attributes où la valeur est stockée.

Supprimer les attributs d'invité

Vous pouvez également supprimer des attributs d'invité. Par exemple, utilisez curl pour supprimer une clé spécifique :

curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/[NAMESPACE]/[KEY] -H "Metadata-Flavor: Google"

où :

• [NAMESPACE] est un groupe logique pour votre [KEY]. Les attributs d'invité doivent avoir un espace de noms.
• [KEY] correspond au chemin d'accès dans guest-attributes où la valeur est stockée.

Désactiver les attributs d'invité de votre organisation ou votre dossier

Si vous ne souhaitez pas que les instances de votre organisation ou de votre dossier activent les attributs d'invité, vous pouvez remplacer et désactiver complètement la fonctionnalité.

Définissez la contrainte constraints/compute.disableGuestAttributesAccess pour votre organisation ou votre dossier :

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess --project [PROJECT_ID]

où [PROJECT_ID] est le nom de votre projet.

Pour en savoir plus sur la définition et la gestion des contraintes dans votre organisation, lisez la section Utiliser des contraintes.

Attendre les mises à jour

Étant donné que les valeurs de métadonnées peuvent changer pendant que votre instance est en cours d'exécution, le serveur de métadonnées vous offre la possibilité de recevoir des notifications en cas de modifications des métadonnées à l'aide de la fonctionnalité d'attente de modification. Cette fonctionnalité vous permet d'effectuer des requêtes HTTP GET qui sont mises en suspens et ne reviennent que lorsque vos métadonnées spécifiées ont changé. Vous pouvez utiliser cette fonctionnalité sur des métadonnées personnalisées ou définies par le serveur. Par conséquent, si des modifications sont apportées à votre instance ou à votre projet, ou si une mise à jour est effectuée sur une métadonnée personnalisée, vous pouvez réagir au changement de manière automatisée. Par exemple, vous pouvez effectuer une requête sur la clé tags afin que la requête ne renvoie une réponse que si le contenu des métadonnées des tags a été modifié. Lorsque la requête est renvoyée, la nouvelle valeur de la clé de métadonnées est spécifiée.

Remarque : Vous ne pouvez effectuer une requête d'attente de modification que sur un point de terminaison de métadonnées ou de manière récursive sur le contenu d'un répertoire. Il n'est pas possible d'effectuer une requête d'attente de modification sur une liste de répertoires. Si vous tentez de le faire, le serveur de métadonnées fait échouer la requête.

Il est également impossible d'effectuer une requête d'attente de modification sur un jeton de compte de service. Si vous essayez d'envoyer une requête d'attente de modification à l'URL du jeton du compte de service, la requête échoue immédiatement.

Dans les deux cas, Google Compute Engine renvoie une erreur 400 – Requête non valide.

Pour effectuer une requête d'attente de modification, interrogez une clé de métadonnées et ajoutez le paramètre de requête ?wait_for_change=true :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"

Après la modification de la clé de métadonnées spécifiée, la requête renvoie la nouvelle valeur. Dans cet exemple, si une requête est transmise à la méthode setInstanceTags, la requête renvoie une réponse incluant les nouvelles valeurs :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"

cheese
lettuce

Vous pouvez également effectuer une requête d'attente de modification de manière récursive sur le contenu d'un répertoire :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"

Le serveur de métadonnées renvoie le nouveau contenu en cas de modification :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"

{"cheese":"lettuce","cookies":"cream"}

La fonctionnalité d'attente de modification vous permet également de faire correspondre votre requête et de définir des délais avant expiration.

Utiliser les ETags

Lorsque vous soumettez une simple requête d'attente de modification, le serveur de métadonnées renvoie une réponse si des modifications ont été apportées dans le contenu de ces métadonnées. Cependant, il existe une condition de concurrence inhérente entre une mise à jour des métadonnées et l'envoi d'une requête d'attente de modification. Il est donc utile de savoir de manière fiable si les valeurs de métadonnées que vous obtenez sont les plus récentes.

Pour vous aider, vous pouvez utiliser le paramètre de requête last_etag qui permet de comparer la valeur ETag que vous avez fournie avec la valeur ETag enregistrée sur le serveur de métadonnées. Si les valeurs ETag correspondent, la requête d'attente de modification est acceptée. Si elles ne correspondent pas, cela indique que le contenu des métadonnées a été modifié depuis votre dernière récupération de la valeur ETag. Le serveur de métadonnées renvoie immédiatement la valeur la plus récente.

Pour récupérer la valeur ETag actuelle associée à une clé de métadonnées, envoyez une requête à cette clé et imprimez les en-têtes. Dans CURL, vous pouvez effectuer cette requête à l'aide du paramètre -v :

user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"

* About to connect() to metadata port 80 (#0)
*   Trying 169.254.169.254... connected
* Connected to metadata (169.254.169.254) port 80 (#0)
> GET /computeMetadata/v1/instance/tags HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
> Host: metadata
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/text
< ETag: 411261ca6c9e654e
< Date: Wed, 13 Feb 2013 22:43:45 GMT
< Server: Metadata Server for VM
< Content-Length: 26
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: SAMEORIGIN
<
cheese
lettuce

Vous pouvez ensuite utiliser cette valeur ETag dans votre requête d'attente de modification :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"

Le serveur de métadonnées fait correspond votre valeur ETag spécifiée. Si cette valeur a été modifiée, la requête renvoie le nouveau contenu de votre clé de métadonnées.

L'exemple Python suivant montre comment surveiller de manière automatisée les modifications apportées dans le serveur de métadonnées :

compute/metadata/main.py

Afficher sur GitHub

last_etag = '0'

while True:
    r = requests.get(
        url,
        params={'last_etag': last_etag, 'wait_for_change': True},
        headers=METADATA_HEADERS)

    # During maintenance the service can return a 503, so these should
    # be retried.
    if r.status_code == 503:
        time.sleep(1)
        continue
    r.raise_for_status()

    last_etag = r.headers['etag']

Remarque : Cet exemple définit l'ETag initial sur 0. Le serveur de métadonnées ne renvoie jamais de réponse avec 0 comme valeur ETag. Lorsque 0 est spécifié comme dernière valeur ETag dans une requête, le serveur de métadonnées répond avec la valeur actuelle et la valeur ETag. Cela permet d'économiser la quantité de code nécessaire pour récupérer la valeur initiale et la valeur ETag.

Définir les délais avant expiration

Si vous souhaitez que votre requête d'attente de modification expire après un certain nombre de secondes, vous pouvez définir le paramètre timeout_sec=<timeout-in-seconds>. Le paramètre timeout_sec permet de limiter le temps d'attente de votre requête au nombre de secondes spécifié. Lorsque la requête atteint cette limite, elle renvoie le contenu actuel de la clé de métadonnées. Voici un exemple de requête d'attente de modification qui est définie pour expirer au bout de 360 secondes :

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"

Lorsque vous définissez le paramètre timeout_sec, la requête renvoie toujours une réponse après le nombre de secondes spécifié, que la valeur de métadonnées ait été réellement modifiée ou non. Le délai avant expiration ne peut être défini qu'avec un nombre entier.

Codes d'état

Lorsque vous effectuez une requête d'attente de modification, le serveur de métadonnées renvoie des codes d'état HTTP standards pour indiquer le succès ou l'échec de l'opération. En cas d'erreurs, le serveur de métadonnées peut faire échouer la requête à cause des conditions du réseau et peut renvoyer un code d'erreur. Pour faire face à ce type de situation, vous devez concevoir votre application de sorte qu'elle soit tolérante aux pannes et capable de reconnaître et gérer ces erreurs.

Les états possibles renvoyés par le serveur de métadonnées sont les suivants :

État	Description
HTTP 200	Opération réussie. Une valeur a été modifiée, ou vous avez atteint la valeur timeout_sec spécifiée, et la requête a bien été renvoyée.
Error 400	La requête n'est pas valide. Corrigez la requête, puis réessayez.
Error 404	La valeur de métadonnées que vous avez spécifiée n'existe plus. Le serveur de métadonnées renvoie également cette erreur si vos métadonnées sont supprimées pendant que vous attendez une modification.
Error 503	Une erreur temporaire du serveur ou un événement temporaire de maintenance s'est produit(e). Réessayez d'envoyer la requête.

Obtenir des notifications relatives à la migration à chaud

Le serveur de métadonnées fournit des informations sur les options et les paramètres de planification d'une instance via le répertoire scheduling/ et l'attribut maintenance-event. Vous pouvez utiliser ces attributs afin d'en savoir plus sur les options de planification d'une instance de VM. De plus, ces métadonnées peuvent vous permettre d'être informé lorsqu'un événement de maintenance est sur le point de survenir via l'attribut maintenance-event. Par défaut, toutes les instances de VM sont configurées pour une migration à chaud afin que le serveur de métadonnées reçoive des notifications d'événements de maintenance avant la migration à chaud d'une instance de VM. Si vous avez choisi d'arrêter l'instance de VM pendant la maintenance, Compute Engine interrompt automatiquement l'instance de VM et peut éventuellement la redémarrer si l'attribut automaticRestart est défini. Pour en savoir plus sur les événements de maintenance et le comportement des instances pendant les événements, consultez la section relative aux options et paramètres de planification.

Vous pouvez savoir quand un événement de maintenance surviendra en interrogeant périodiquement l'attribut maintenance-event. La valeur de cet attribut change 60 secondes avant le début d'un événement de maintenance, ce qui permet au code de l'application de déclencher les tâches que vous souhaitez effectuer avant un événement de maintenance, comme la sauvegarde des données ou la mise à jour des journaux. Compute Engine propose également un exemple de script Python pour montrer comment vérifier les notifications d'événements de maintenance.

Remarque : Pour les instances avec des GPU, l'attribut change 60 minutes avant l'arrêt des instances pour vous donner le temps d'arrêter l'instance et de la redémarrer sur un autre hôte. Les instances avec des GPU ne sont pas migrées à chaud, mais sont arrêtées et éventuellement redémarrées. Pour en savoir plus, consultez la section Gérer les événements de maintenance de l'hôte dans la documentation relative aux GPU.

Compute Engine ne déclenche l'avertissement de 60 secondes que dans les cas suivants :

• Vous avez défini les options de disponibilité de l'instance pour la migration à chaud lors d'un événement de maintenance.

• Vous avez interrogé l'attribut maintenance-event au moins une fois depuis le dernier événement de maintenance. Si vous n'avez jamais interrogé l'attribut maintenance-event ou si vous n'avez pas interrogé l'attribut depuis la dernière migration, Compute Engine suppose que l'instance ne nécessite pas d'avertissement préalable pour les événements de maintenance. L'événement de maintenance ignore l'avertissement de 60 secondes et se déclenche immédiatement. Si vous ne souhaitez pas que l'avertissement de 60 secondes soit ignoré, assurez-vous que le code client interroge l'attribut maintenance-event au moins une fois entre les événements de migration.

Remarque : Vous devez interroger directement l'attribut maintenance-event pour que Compute Engine détermine que vous surveillez cet attribut. L'interrogation de métadonnées de niveau supérieur ne déclenche pas la notification préalable.

Pour interroger l'attribut maintenance-event, procédez comme suit :

user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"

NONE

La valeur initiale et par défaut de l'attribut maintenance-event est NONE. Avant qu'un événement de maintenance transparence ne commence, la valeur maintenance-event est modifiée comme suit :

1. La valeur passe de NONE à MIGRATE_ON_HOST_MAINTENANCE.
2. Pendant toute la durée de l'événement et pendant la migration à chaud de la VM, la valeur reste MIGRATE_ON_HOST_MAINTENANCE.
3. Une fois l'événement de maintenance terminé, la valeur revient à NONE.

Attention : L'attribut maintenance-event ne sera renseigné pour les événements de maintenance que si vous avez défini l'option de planification de votre instance sur migrate ou si votre instance est associée à un GPU. Les instances de VM sans GPU définies sur terminate sont arrêtées, puis redémarrées, et ne sont pas informées des événements de maintenance via cet attribut.

Vous pouvez vous servir de l'attribut maintenance-event avec la fonctionnalité d'attente de mises à jour pour notifier vos scripts et applications lorsqu'un événement de maintenance est sur le point de démarrer et de se terminer. Cela vous permet d'automatiser toutes les actions que vous souhaitez exécuter avant ou après l'événement. L'exemple Python suivant fournit un exemple de mise en œuvre de ces deux fonctionnalités.

Remarque : Lors de l'événement de maintenance, le serveur de métadonnées peut renvoyer brièvement un code 503 Service Unavailable. Si votre application reçoit un code d'erreur 503, vous devez réessayer d'envoyer votre requête.

compute/metadata/main.py

Afficher sur GitHub

import time

import requests

METADATA_URL = 'http://metadata.google.internal/computeMetadata/v1/'
METADATA_HEADERS = {'Metadata-Flavor': 'Google'}

def wait_for_maintenance(callback):
    url = METADATA_URL + 'instance/maintenance-event'
    last_maintenance_event = None
    last_etag = '0'

    while True:
        r = requests.get(
            url,
            params={'last_etag': last_etag, 'wait_for_change': True},
            headers=METADATA_HEADERS)

        # During maintenance the service can return a 503, so these should
        # be retried.
        if r.status_code == 503:
            time.sleep(1)
            continue
        r.raise_for_status()

        last_etag = r.headers['etag']

        if r.text == 'NONE':
            maintenance_event = None
        else:
            maintenance_event = r.text

        if maintenance_event != last_maintenance_event:
            last_maintenance_event = maintenance_event
            callback(maintenance_event)

def maintenance_callback(event):
    if event:
        print('Undergoing host maintenance: {}'.format(event))
    else:
        print('Finished host maintenance')

def main():
    wait_for_maintenance(maintenance_callback)

if __name__ == '__main__':
    main()

Passer à v1

Le serveur de métadonnées v1 fonctionne légèrement différemment du serveur v1beta1 précédent. Voici quelques modifications à apporter au nouveau serveur de métadonnées :

• Mettre à jour les requêtes de métadonnées afin d'inclure l'en-tête Metadata-Flavor: Google

  Le nouveau serveur de métadonnées exige que toutes les requêtes contiennent l'en-tête Metadata-Flavor: Google. Ce dernier indique que la requête a été effectuée afin de récupérer les valeurs de métadonnées. Mettez à jour vos requêtes de manière à inclure ce nouvel en-tête. Par exemple, voici à quoi ressemble désormais une requête envoyée à l'attribut disks/ :

  user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
  

• Mettre à jour les requêtes qui utilisent l'en-tête X-Forwarded-For

  Ces requêtes sont automatiquement refusées par le serveur, car elles indiquent généralement que les requêtes sont transmises par serveur proxy. Mettez à jour vos requêtes afin qu'elles ne contiennent pas cet en-tête.

Étapes suivantes

• Obtenez plus d'informations sur l'exécution des scripts de démarrage ou des scripts d'arrêt sur le serveur de métadonnées.
• En savoir plus sur la migration à chaud.