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

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. Vous pouvez rechercher 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 toutes les instances, vous pouvez réutiliser votre script sans avoir à le mettre à jour pour chacune d'entre elles. 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.

Les points de terminaison du serveur de métadonnées v1beta1 et v0.1 sont obsolètes depuis le 30 septembre 2020 et sont en cours d'arrêt. Veillez à mettre à jour toutes les requêtes de sorte qu'elles utilisent la version v1. Pour en savoir plus, consultez la section Passer au point de terminaison du serveur de métadonnées v1.

Pour savoir comment vérifier la version du point de terminaison de votre serveur de métadonnées, consultez la section Vérifier la version du point de terminaison de votre serveur.

Avant de commencer

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 simplement obtenir des métadonnées
  • compute.instances.get sur l'instance, si vous souhaitez simplement obtenir des métadonnées

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

Les métadonnées peuvent être attribuées à des projets et à des instances. Les métadonnées d'un projet se propagent sur toutes les instances de machine virtuelle (VM) de celui-ci, tandis que les métadonnées au niveau d'une instance n'affectent que cette instance.

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

Compute Engine définit un ensemble d'entrées de métadonnées par défaut qui fournissent des informations sur votre instance ou votre 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.

Les métadonnées suivantes sont disponibles par défaut 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/ est un répertoire qui contient d'autres clés, tandis que numeric-project-id est une clé de métadonnées mappée avec une valeur.

Par rapport à 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, sauf si le projet utilise d'anciens points de terminaison. Mettez à jour vos applications de sorte qu'elles utilisent les 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 au système d'exploitation ne sont pas visibles dans cette valeur de métadonnées.

Exemple "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

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 Google Cloud Console. Cette valeur est différente de la valeur d'entrée de métadonnées project-id.
project-id ID du projet.

Les métadonnées suivantes sont disponibles par défaut pour une instance :

Par rapport à 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 Spécifier 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 au système d'exploitation ne sont pas visibles dans cette valeur de métadonnées.

Exemple : "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"
cpu-platform Plate-forme du processeur de l'instance.
description Description en texte libre d'une instance attribuée à l'aide de l'option --description ou définie dans l'API.
disks/ Répertoire des 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 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, qui est au format suivant : projects/projectnum/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'option --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'option ‑‑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. Pour plus de détails, consultez la section Notifications de maintenance transparente.
service-accounts/ Répertoire des comptes de service associés à l'instance.
service-accounts/service-account-name/token Jeton d'accès OAuth2 pouvant être utilisé pour authentifier des applications.
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/projectnum/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.

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

Toutes les requêtes contenant l'en-tête X-Forwarded-For sont automatiquement rejeté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 :

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

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 (@).

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

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 machine virtuelle.

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és à 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 obtenir 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 souhaitez renvoyer ces contenus au format texte, ajoutez le paramètre de requête 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 valeurs booléennes

Dans les champs qui acceptent les valeurs booléennes, telles que TRUE ou FALSE, vous pouvez également utiliser les valeurs suivantes :

État Autres valeurs
TRUE O, Oui, 1
Faux N, Non, 0

Les valeurs booléennes ne sont pas sensibles à la casse. Par exemple, vous pouvez utiliser False, false ou FALSE pour désactiver une fonctionnalité.

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

Vous pouvez définir des métadonnées personnalisées pour une instance ou un projet depuis Google Cloud Console, l'outil de ligne de commande gcloud ou 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

Compute Engine applique une limite totale combinée de 512 Ko pour toutes les entrées de métadonnées. Des limites de taille maximale sont également appliquées à chaque key et value comme suit :

  • Chaque métadonnée key est limitée à 128 octets.
  • Chaque métadonnée value est limitée à 256 Ko.

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 Cloud Storage, puis fournissez l'URL du script de démarrage lors de la création d'une instance. Ces fichiers sont 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 des métadonnées personnalisées pour une instance dans Cloud Console, l'outil gcloud ou l'API. Les métadonnées d'instance ne s'appliquent qu'à une instance spécifique.

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

Console

  1. Dans Cloud Console, 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, renseignez les propriétés de 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, définissez des métadonnées personnalisées à l'aide de l'option --metadata.

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://compute.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. Dans Google Cloud Console, accédez à la page Instances de VM.

    Accéder à 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-name \
      --metadata bread=mayo,cheese=cheddar,lettuce=romaine

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

gcloud compute instances add-metadata instance-name \
    --metadata lettuce=green

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

gcloud compute instances remove-metadata instance-name \
    --keys lettuce

API

Dans l'API, envoyez une requête à la méthode instances().setMetadata. Fournissez la liste des nouvelles valeurs de métadonnées et la valeur 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://compute.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://compute.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 instances().setMetadata aboutisse :

POST https://compute.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. Dans Google Cloud Console, accédez à la page Métadonnées.

    Accéder à 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 de l'option --metadata-from-file. Vous pouvez supprimer des valeurs de métadonnées à l'aide de 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.

Pour effectuer un verrouillage optimiste, vous pouvez éventuellement fournir une empreinte. Une empreinte est une chaîne aléatoire de caractères générée par Compute Engine. L'empreinte change après chaque requête. Si vous fournissez une empreinte non concordante, votre requête est refusée.

Si vous ne fournissez pas d'empreinte, aucune vérification de cohérence n'est effectuée et la requête projects().setCommonInstanceMetadata aboutit. Ce comportement est différent de instances().setMetadata, où une empreinte est toujours requise.

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

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

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

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

POST https://compute.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'instances ou de projets via Cloud Console, 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 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[]"

Définissez le champ d'application de la sortie sur une clé de métadonnées appropriée à l'aide de l'option --flatten. Par exemple, l'instance suivante a 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://compute.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://compute.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é

N'utilisez les attributs d'invité que pour les cas d'utilisation nécessitant de petites quantités de données qui ne changent pas fréquemment. 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 trois 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 qui peuvent signaler le succès d'une initialisation en définissant une valeur d'état personnalisée dans les attributs d'invité
  • Les agents de gestion de la configuration qui peuvent publier le nom et la version d'un système d'exploitation invité dans les attributs d'invité
  • Les agents de gestion de l'inventaire qui peuvent publier la liste des packages installés dans l'instance de VM dans les attributs d'invité
  • Les logiciels d'orchestration de charge de travail qui 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 d'invité

Les attributs d'invité ne remplacent pas la diffusion en continu d'événements, Pub/Sub ou d'autres formes de dépôts de configuration et de stockage de données.

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 ne peut lire ou écrire que sur son propre serveur de métadonnées. Le serveur de métadonnées d'une instance spécifique est inaccessible aux autres instances. 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 (gestion de l'authentification et des accès) 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 de l'instance lorsque vous la créez :

  1. Dans Google Cloud Console, accédez à la page Instances de VM.

    Accéder à la page "Instances de VM"

  2. Cliquez sur Create instance (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 de l'appliquer à toutes les instances de votre projet :

  1. Dans Google Cloud Console, accédez à la page Métadonnées.

    Accéder à la page "Métadonnées"

  2. Cliquez sur Modifier.

  3. Ajoutez une entrée de métadonnées, avec enable-guest-attributes comme clé et TRUE comme valeur. 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. Dans Google Cloud Console, accédez à la page Instances de VM.

    Accéder à 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 avec enable-guest-attributes comme clé et TRUE comme valeur. 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-guest-attributes dans les métadonnées de l'instance lorsque vous la créez :

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é. Remplacez instance-name par le nom de votre instance.

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éfinir 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é. Remplacez instance-name par le nom de votre instance.

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 l'instance de machine virtuelle peut écrire dans les valeurs des attributs d'invité, y compris les scripts et les applications qui ne possèdent pas de privilèges 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 aux métadonnées guest-attributes :

curl -X PUT --data "value" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/namespace/key -H "Metadata-Flavor: Google"

Remplacez les éléments suivants :

  • namespace : regroupement logique de votre clé (key). Les attributs d'invité doivent avoir un espace de noms.
  • value : valeur que vous souhaitez écrire.
  • key : chemin d'accès aux métadonnées dans guest-attributes où la valeur est stockée.

N'utilisez que des lettres, des chiffres, des traits de soulignement (_) et des tirets (-) dans les champs namespace et key.

Obtenir les attributs d'invité

Les utilisateurs ou les comptes de service peuvent lire les attributs d'invité s'ils disposent d'un rôle IAM qui fournit l'autorisation compute.instances.getGuestAttributes. N'importe quel utilisateur ou n'importe quelle 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 machine virtuelle peut écrire dans la valeur des attributs d'invité, y compris les scripts et les applications qui ne possèdent pas de privilèges 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 aux métadonnées guest-attributes :

curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/namespace/key -H "Metadata-Flavor: Google"

Remplacez les éléments suivants :

  • namespace : espace de noms de la clé guest-attributes que vous souhaitez interroger.
  • key : chemin d'accès dans guest-attributes à partir duquel vous souhaitez lire la valeur des métadonnées.

Vous pouvez également afficher toutes les valeurs d'attribut d'invité en une seule requête. Remplacez namespace par l'espace de noms de la clé guest-attributes que vous souhaitez interroger.

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

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'option --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'option --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

Remplacez les éléments suivants :

  • instance-name : nom de l'instance à partir de laquelle vous souhaitez lire la valeur de métadonnées de l'attribut d'invité.
  • namespace : espace de noms de la clé guest-attributes que vous souhaitez interroger.
  • key : chemin d'accès dans les métadonnées guest-attributes où la valeur est stockée.
  • zone : zone où se trouve l'instance.

API

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

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes?queryPath=namespace/key

Remplacez les éléments suivants :

  • project-id : ID de votre projet.
  • zone : zone où se trouve votre instance.
  • instance-name : nom de l'instance à partir de laquelle vous souhaitez lire la valeur de métadonnées de l'attribut d'invité.
  • namespace : espace de noms de la clé guest-attributes que vous souhaitez interroger.
  • key : chemin d'accès dans les métadonnées guest-attributes où la valeur est stockée.

Pour récupérer toutes les clés d’un namespace, omettez la key :

GET https://compute.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 entièrement namespace et queryPath :

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes

Sinon, si vous disposez d'un jeton OAuth, vous pouvez utiliser curl :

curl -H "Authorization: Bearer oauth-token" https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/instance-name/getGuestAttributes?queryPath=namespace/key

Remplacez les éléments suivants :

  • oauth-token : votre jeton OAuth.
  • project-id : ID de votre projet.
  • zone : zone où se trouve votre instance.
  • instance-name : nom de l'instance à partir de laquelle vous souhaitez lire la valeur de métadonnées de l'attribut d'invité.
  • namespace : espace de noms de la clé guest-attributes que vous souhaitez interroger.
  • key : chemin d'accès dans les métadonnées guest-attributes où la valeur est stockée.

Supprimer les attributs d'invité

Vous pouvez également supprimer des attributs d'invité. Par exemple, supprimez une clé spécifique à l'aide de curl :

curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/namespace/key -H "Metadata-Flavor: Google"

Remplacez les éléments suivants :

  • namespace : espace de noms de la clé guest-attributes que vous souhaitez supprimer.
  • key : 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 ignorer la fonctionnalité et la désactiver complètement.

Définissez la contrainte constraints/compute.disableGuestAttributesAccess sur votre organisation ou votre dossier, et remplacez project-id par le nom de votre projet :

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess \
    --project project-id

Pour en savoir plus sur la définition et la gestion des contraintes dans votre organisation, consultez la page 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 peut 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.

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 obtenir la valeur ETag actuelle d'une clé de métadonnées, envoyez une requête à cette clé et imprimez les en-têtes. Dans curl, vous pouvez le faire à l'aide de l'option -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 correspondre la valeur ETag que vous avez 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 
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']

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 Success! 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 machine virtuelle. 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 machines virtuelles 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 l'arrête automatiquement 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 sur les options et les 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.

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.

Pour interroger l'attribut maintenance-event :

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.

  • Sur les instances GPU, l'attribut passe de NONE à TERMINATE_ON_HOST_MAINTENANCE lors d'un événement de maintenance. Cet attribut est mis à jour 60 minutes avant le début de l'événement d'arrêt.

  • Sur les instances sans GPU disposant d'une option de planification de migration (migrate), l'attribut maintenance-event est remplacé comme suit :

    1. Au début de l'événement de migration, la valeur passe de NONE à MIGRATE_ON_HOST_MAINTENANCE. Cet attribut est mis à jour 60 minutes avant le début de l'événement d'arrêt.
    2. Pendant toute la durée de l'événement et pendant la migration à chaud de votre instance de VM, la valeur reste MIGRATE_ON_HOST_MAINTENANCE.
    3. Une fois l'événement de maintenance terminé, la valeur revient à NONE.

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.

Exemple de script Python permettant d'interroger les événements de maintenance

compute/metadata/main.py 

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()

Vérifier la version du point de terminaison de votre serveur

Version actuelle : v1

Compute Engine peut offrir plusieurs versions de métadonnées. Toutefois, nous vous recommandons de toujours utiliser la version la plus récente du serveur de métadonnées disponible. À tout moment, 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.

Pour vérifier la version du point de terminaison de votre serveur de métadonnées, consultez l'URI que vous utilisez pour envoyer des requêtes au serveur.

Version du point de terminaison des métadonnées URI
v0.1 (obsolète) http://metadata.google.internal/0.1/meta-data/…
v1beta1 (obsolète) http://metadata.google.internal/computeMetadata/v1beta1/…
v1 http://metadata.google.internal/computeMetadata/v1/…

Désactiver les anciens points de terminaison

Vous pouvez désactiver ces points de terminaison au niveau du projet ou de l'instance.

Pour désactiver les points de terminaison du serveur de métadonnées v0.1 et v1beta1, suivez les instructions concernant la définition de métadonnées personnalisées, puis définissez disable-legacy-endpoints=TRUE.

Par exemple, pour désactiver le point de terminaison du serveur de métadonnées, exécutez la commande suivante au niveau du projet à l'aide de l'outil de ligne de commande gcloud :

gcloud compute project-info add-metadata \
    --metadata disable-legacy-endpoints=TRUE

Passer au point de terminaison du serveur de métadonnées v1

Pour savoir comment passer de v1.1 ou v1beta1 au point de terminaison v1, consultez la page Migrer vers le point de terminaison du serveur de métadonnées v1.

Étape suivante