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.

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

Les points de terminaison du serveur de métadonnées v0.1 et du serveur v1beta1 sont obsolètes, et leur abandon est planifié. 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.

Avant de commencer

• Si vous souhaitez utiliser les exemples de ligne 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 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 d'OS Login 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 d'OS Login, 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 OS Login 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 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 d'OS Login 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 d'OS Login, 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 OS Login 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 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-attributes".
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/[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'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 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>/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. Par exemple, "?audience=http://www.example.com". Consultez la page Vérifier l'identité des instances pour savoir comment demander et vérifier 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 ne pouvez interroger des valeurs de métadonnées par défaut qu'à 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 obligatoire dans les requêtes. Ces deux en-têtes sont toujours acceptés, mais nous vous recommandons 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 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/[e-mail]/?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, ajoutez le paramètre recursive=true à 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 applicables à la taille des métadonnées personnalisées

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

console true

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 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 et 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, 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.

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 Cloud Identity and Access Management 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. Accédez à la page Instances de VM dans Google Cloud Console.

   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 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. Accédez à la page Instances de VM dans Google Cloud Console.

   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 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é. 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 de l'appliquer à 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é. 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 envoyer 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 l'élément suivant :

• 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 possèdent un rôle Cloud 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 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 envoyer 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 l'élément suivant :

• 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 l'élément suivant :

• 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 l'élément suivant :

• 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 l'élément suivant :

• 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.

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, 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 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

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 ETag. Lorsque la valeur 0 est spécifiée comme dernier ETag dans une requête, le serveur de métadonnées répond avec la valeur actuelle et l'ETag. Cela permet d'économiser la quantité de code nécessaire pour obtenir la valeur initiale et l'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 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 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 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.

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 sur les 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 :

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

Attention : L'attribut maintenance-event n'est renseigné pour les événements de maintenance que si vous avez défini l'option de planification de votre instance sur migrate ou si un GPU est associé à votre instance. Les instances de machines virtuelles 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.

La valeur initiale et par défaut de l'attribut maintenance-event est NONE.

Sur les instances de 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 de terminaison.

Sur les instances sans GPU disposant d'une option de planification 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.
2. Pendant toute la durée de l'événement et pendant la migration 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.

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.

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

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

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

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	http://metadata.google.internal/0.1/meta-data/…
v1beta1	http://metadata.google.internal/computeMetadata/v1beta1/…
v1	http://metadata.google.internal/computeMetadata/v1/…

Désactiver les anciens points de terminaison

En vue de l'arrêt des points de terminaison du serveur de métadonnées v0.1 et v1beta1, 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 v0.1 ou v1beta1 au point de terminaison v1, consultez la page Migrer vers le point de terminaison du serveur de métadonnées v1.

É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.
• Apprenez-en plus sur la migration à chaud.