Afficher et interroger les métadonnées d'une VM

Chaque machine virtuelle (VM) stocke ses métadonnées dans des répertoires sur un serveur de métadonnées. Votre VM a automatiquement accès à l'API de ce serveur de métadonnées, sans aucune autorisation supplémentaire. Vous pouvez utiliser les méthodes expliquées dans les sections suivantes de ce document pour afficher et interroger les valeurs de métadonnées de VM :

Si vous rencontrez des erreurs lorsque vous accédez au serveur de métadonnées, consultez la section Résoudre les problèmes d'accès au serveur de métadonnées.

Avant de commencer

  • Pour les VM Windows Server, utilisez PowerShell 3.0 ou version ultérieure. Nous vous recommandons d'utiliser ctrl+v pour coller les blocs de code copiés.
  • Examinez les principes de base de la définition, la classification et l'organisation des métadonnées de VM pour Compute Engine. Pour en savoir plus, consultez la page À propos des métadonnées de VM.
  • Si ce n'est pas déjà fait, configurez l'authentification. L'authentification est le processus permettant de valider votre identité pour accéder aux services et aux API Google Cloud. Pour exécuter du code ou des exemples depuis un environnement de développement local, vous pouvez vous authentifier auprès de Compute Engine en sélectionnant l'une des options suivantes:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

      3. Python

      Pour utiliser les exemples Python de cette page dans un environnement de développement local, installez et initialisez gcloud CLI, puis configurez le service Identifiants par défaut de l'application à l'aide de vos identifiants utilisateur.

      1. Install the Google Cloud CLI.

      2. To initialize the gcloud CLI, run the following command: 

        gcloud init

      3. If you're using a local shell, then create local authentication credentials for your user account: 

        gcloud auth application-default login

        You don't need to do this if you're using Cloud Shell.

      Pour en savoir plus, consultez Set up authentication for a local development environment.

      REST

      Pour utiliser les exemples d'API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à gcloud CLI.

        Install the Google Cloud CLI, then initialize it by running the following command: 

        gcloud init

      Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud.

Rôles requis

Les rôles et autorisations suivants sont nécessaires pour afficher des métadonnées personnalisées depuis l'extérieur de la VM à l'aide de la console Google Cloud, de la Google Cloud CLI ou de REST. Si vous interrogez les métadonnées de manière programmatique à partir de la VM, vous n'avez besoin que des rôles et des autorisations nécessaires pour vous connecter à la VM.

Pour obtenir les autorisations nécessaires pour afficher des métadonnées personnalisées extérieures à la VM, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour afficher les métadonnées personnalisées depuis l'extérieur de la VM. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour afficher les métadonnées personnalisées depuis l'extérieur de la VM :

  • Pour afficher les métadonnées personnalisées d'un projet : compute.projects.get sur le projet
  • Pour afficher les métadonnées zonales personnalisées : compute.instanceSettings.get sur les paramètres d'instance dans la zone requise par le projet
  • Pour afficher des métadonnées personnalisées pour une instance de VM : compute.instances.get sur la VM
  • Si vos VM utilisent des comptes de service : iam.serviceAccounts.actAs sur les comptes de service ou le projet

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Interroger les métadonnées de manière automatisée

Vous pouvez accéder à toutes les métadonnées en interrogeant les entrées de valeur de métadonnées de manière automatisée à partir d'une VM Linux ou Windows. À partir de votre VM, vous pouvez interroger de manière automatisée vos valeurs de métadonnées de l'une des manières suivantes à l'aide d'outils tels que curl sous Linux ou Invoke-RestMethod sous Windows :

Points de terminaison du serveur de métadonnées

Pour interroger de manière automatisée les métadonnées à partir d'une VM, vous disposez des points de terminaison de serveur de métadonnées suivants :

  • Pour toutes les VM, vous pouvez interroger le serveur de métadonnées à l'aide du point de terminaison HTTP (http://metadata.google.internal/computeMetadata/v1).

  • Pour les VM protégées, vous pouvez interroger le serveur de métadonnées à l'aide de l'une des méthodes suivantes :

La plupart des exemples de ce document utilisent le point de terminaison http. Toutefois, vous pouvez accéder à toutes les entrées de métadonnées, que vous utilisiez le point de terminaison https ou http.

Composantes d'une requête de métadonnées

Le tableau suivant récapitule les principaux composants d'une requête de métadonnées.

Composants Description
URL racine

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

  • Point de terminaison http : 
    • http://metadata.google.internal/computeMetadata/v1
    • http://169.254.169.254/computeMetadata/v1
    • http://metadata.goog/computeMetadata/v1
  • Point de terminaison https (preview) : 
    • https://metadata.google.internal/computeMetadata/v1
      Il s'agit de la seule URL acceptée pendant la phase preview.
En-tête de requête

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.

Metadata-Flavor: Google

Interroger une seule entrée de métadonnées

Utilisez les commandes suivantes pour interroger une seule entrée de métadonnées.

Linux

  1. Connectez-vous à la VM Linux.

  2. À partir de votre VM Linux, utilisez l'outil curl pour envoyer une requête. Pour interroger une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"

    Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

    • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
    • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
    • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.

    Par exemple, pour interroger l'image de démarrage de la VM, exécutez la requête suivante :

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

    Le résultat ressemble à ce qui suit :

    projects/rhel-cloud/global/images/rhel-8-v20210122

Windows

  1. Connectez-vous à votre VM Windows.

  2. À partir de votre VM Windows, exécutez la commande Invoke-RestMethod pour effectuer une requête. Pour interroger une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

    $value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
$value

    Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

    • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
    • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
    • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.

    Par exemple, pour interroger l'image de démarrage de la VM, exécutez la requête suivante :

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/image")
$value

    Le résultat ressemble à ce qui suit :

    projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

Interroger les listes de répertoires de métadonnées

Utilisez les commandes suivantes pour interroger les fiches de répertoire de métadonnées. Les fiches de répertoire sont des entrées de métadonnées contenant d'autres clés de métadonnées. Toute entrée de métadonnées se terminant par une barre oblique correspond à une liste de répertoires.

Linux

  1. Connectez-vous à la VM Linux.

  2. Pour interroger un répertoire de métadonnées d'instance de VM ou de projet à partir de votre VM Linux, exécutez la commande suivante :

      curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/" -H "Metadata-Flavor: Google"

    Remplacez PATH_TO_METADATA_DIRECTORY par le chemin d'accès à l'instance de VM ou au répertoire de métadonnées du projet dont vous souhaitez interroger les listes de manière récursive. Exemple :

    • Pour afficher l'entrée de répertoire des métadonnées du projet attributes, le chemin à spécifier est project/attributes/.
    • Pour afficher l'entrée de répertoire des métadonnées de l'instance de VM disks, le chemin à spécifier est instance/disks/.

    Prenons l'exemple de l'entrée disks/, qui est un répertoire de disques associé à la VM. Pour interroger l'entrée disks/, procédez comme suit :

    1. Exécutez la commande de l'outil curl sur le répertoire de disques.

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

      Le résultat ressemble à ce qui suit :

      0/
1/
2/

    2. Si vous souhaitez obtenir plus d'informations sur le répertoire de disque 0/, vous pouvez ensuite 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"

      Le résultat ressemble à ce qui suit :

      device-name
index
mode
type

    3. Pour connaître le type de disque (type) des disques 0/, vous pouvez exécuter la commande suivante :

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

      Le résultat ressemble à ce qui suit :

      PERSISTENT

Windows

L'entrée disks/ désigne un répertoire de disques associé à la VM. Pour interroger l'entrée de disque, procédez comme suit :

  1. Connectez-vous à votre VM Windows.

  2. Pour interroger un répertoire de métadonnées d'instance de VM ou de projet à partir de votre VM Windows, exécutez la commande suivante :

    $value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/")
$value

    Remplacez PATH_TO_METADATA_DIRECTORY par le chemin d'accès à l'instance de VM ou au répertoire de métadonnées du projet dont vous souhaitez interroger les listes de manière récursive. Exemple :

    • Pour afficher l'entrée de répertoire des métadonnées du projet attributes, le chemin à spécifier est project/attributes/.
    • Pour afficher l'entrée de répertoire des métadonnées de l'instance de VM disks, le chemin à spécifier est instance/disks/.

    Prenons l'exemple de l'entrée disks/, qui est un répertoire de disques associé à la VM. Pour interroger l'entrée disks/, procédez comme suit :

    1. Exécutez la commande Invoke-RestMethod sur le répertoire de disques.

      PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/")
$value

      Le résultat ressemble à ce qui suit :

      0/
1/
2/

    2. Si vous souhaitez en savoir plus sur le répertoire de disque 0/, vous pouvez interroger l'URL spécifique de ce répertoire :

      PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/")
$value

      Le résultat ressemble à ce qui suit :

      device-name
index
mode
type

    3. Pour connaître le type de disque (type) des disques 0/, vous pouvez exécuter la commande suivante :

      PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/0/type")
$value

      Le résultat ressemble à ce qui suit :

      PERSISTENT

Interroger les listes de répertoires 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 :

Linux

  1. Connectez-vous à la VM Linux.

  2. À partir de votre VM Linux, utilisez l'outil curl pour envoyer une requête. Pour interroger de manière récursive les fiches d'un répertoire de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true" -H "Metadata-Flavor: Google"

    Remplacez PATH_TO_METADATA_DIRECTORY par le chemin d'accès à l'instance de VM ou au répertoire de métadonnées du projet dont vous souhaitez interroger les listes de manière récursive. Exemple :

    • Pour afficher l'entrée de répertoire des métadonnées du projet attributes, le chemin à spécifier est project/attributes/.
    • Pour afficher l'entrée de répertoire des métadonnées de l'instance de VM disks, le chemin à spécifier est instance/disks/.

    Par exemple, la commande suivante interroge de manière récursive les fiches de métadonnées d'instance pour le répertoire disks/.

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

    Le résultat ressemble à ce qui suit :

      [{"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"

    Le résultat ressemble à ce qui suit :

      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

Windows

  1. Connectez-vous à votre VM Windows.

  2. À partir de votre VM Windows, exécutez la commande Invoke-RestMethod pour effectuer une requête. Pour interroger de manière récursive les fiches d'un répertoire de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_DIRECTORY/?recursive=true")
  $value

    Remplacez PATH_TO_METADATA_DIRECTORY par le chemin d'accès à l'instance de VM ou au répertoire de métadonnées du projet dont vous souhaitez interroger les listes de manière récursive. Exemple :

    • Pour afficher l'entrée de répertoire des métadonnées du projet attributes, le chemin à spécifier est project/attributes/.
    • Pour afficher l'entrée de répertoire des métadonnées de l'instance de VM disks, le chemin à spécifier est instance/disks/.

    Par exemple, la commande suivante interroge de manière récursive les fiches de métadonnées d'instance pour le répertoire disks/.

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true")
$value

    Le résultat ressemble à ce qui suit :

    [{"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 :

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text")
$value

    Le résultat ressemble à ce qui suit :

    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

Mettre en forme le résultat d'une requête

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.

Linux

  1. Connectez-vous à la VM Linux.

  2. À partir de votre VM Linux, utilisez l'outil curl pour envoyer une requête. Pour modifier le format des données de réponse de requête pour une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT" -H "Metadata-Flavor: Google"

    Remplacez les éléments suivants :

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.
    • DATA_FORMAT : format dans lequel vous souhaitez obtenir les données de réponse de la requête, par exemple text ou json.

Exemple

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 les données au format texte.

Requête par défaut

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

Le résultat ressemble à ce qui suit :

  ["http-server", "db-client", "app-server", "mysql-server"]

Requête avec mise en forme

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

Le résultat ressemble à ce qui suit :

  http-server
  db-client
  app-server
  mysql-server

Windows

  1. Connectez-vous à votre VM Windows.

  2. À partir de votre VM Windows, exécutez la commande Invoke-RestMethod pour effectuer une requête. Pour modifier le format des données de réponse de requête pour une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?alt=DATA_FORMAT")
  $value

    Remplacez les éléments suivants :

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.
    • DATA_FORMAT : format dans lequel vous souhaitez obtenir les données de réponse de la requête, par exemple text ou json.

Exemple

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 les données au format texte.

Requête par défaut

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags")
  $value

Le résultat ressemble à ce qui suit :

  ["http-server", "db-client", "app-server", "mysql-server"]

Requête avec mise en forme

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text")
  $value

Le résultat ressemble à ce qui suit :

  http-server
  db-client
  app-server
  mysql-server

Interroger les modifications de métadonnées à l'aide de la fonctionnalité wait-for-change

Étant donné que les valeurs de métadonnées peuvent changer pendant que votre VM 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é wait-for-change. Avec cette option, la requête ne renvoie un résultat que lorsque les métadonnées spécifiées ont été modifiées.

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

La fonctionnalité wait-for-change vous permet également de faire correspondre votre requête et de définir des délais avant expiration.

Lorsque vous utilisez la fonctionnalité wait-for-change, tenez compte des points suivants :

  • Vous ne pouvez exécuter une requête wait-for-change que sur un point de terminaison de métadonnées ou de manière récursive sur le contenu d'un répertoire. Vous ne pouvez pas exécuter de requête wait-for-change sur une liste de répertoires. Si vous tentez de le faire, le serveur de métadonnées fait échouer la requête et renvoie une erreur 400 Requête non valide.

  • Vous ne pouvez pas envoyer une requête wait-for-change pour un jeton de compte de service. Si vous essayez d'envoyer une requête wait-for-change à l'URL du jeton du compte de service, la requête échoue immédiatement et renvoie une erreur 400 Requête non valide.

Pour envoyer une requête wait-for-change, interrogez une clé de métadonnées et ajoutez le paramètre de requête ?wait_for_change=true :

Linux

  1. Connectez-vous à la VM Linux.

  2. À partir de votre VM Linux, utilisez l'outil curl pour envoyer une requête. Pour envoyer une requête wait-for-change pour une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

    curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true" -H "Metadata-Flavor: Google"

    Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

    • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
    • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
    • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.

    Après la modification de la clé de métadonnées spécifiée, la requête renvoie la nouvelle valeur.

Exemples

Dans cet exemple, si une requête est transmise à la méthode setInstanceTags method, 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"

Le résultat ressemble à ce qui suit :

  http-server
  db-client

Vous pouvez également envoyer une requête wait-for-change 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 :

  {"foo":"bar","baz":"bat"}

Windows

  1. Connectez-vous à votre VM Windows.

  2. À partir de votre VM Windows, exécutez la commande Invoke-RestMethod pour effectuer une requête. Pour envoyer une requête wait-for-change pour une instance de VM ou une entrée de métadonnées de projet, exécutez la commande suivante :

    $value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true")
$value

    Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

    • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
    • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
    • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.

    Après la modification de la clé de métadonnées spécifiée, la requête renvoie la nouvelle valeur.

Exemples

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 method, la requête renvoie une réponse incluant les nouvelles valeurs :

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true")
  $value

Le résultat ressemble à ce qui suit :

  http-server
  db-client

Vous pouvez également envoyer une requête wait-for-change de manière récursive sur le contenu d'un répertoire :

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/attributes?recursive=true&wait_for_change=true")
  $value

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

  {"foo":"bar","baz":"bat"}

Utiliser les ETags

Lorsque vous soumettez une requête wait-for-change, 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 wait-for-change. 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 wait-for-change 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.

VM Linux

Pour obtenir la valeur ETag actuelle d'une clé de métadonnées, procédez comme suit :

  1. Connectez-vous à la VM Linux.

  2. Envoyez une requête à cette clé et imprimez les en-têtes. Pour ce faire, utilisez l'outil curl avec l'option -v. Pour obtenir l'ETag actuel d'une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

    curl -v "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" -H "Metadata-Flavor: Google"

    Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

    • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
    • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
    • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.

    Par exemple, la commande suivante obtient la valeur ETag actuelle pour la clé de métadonnées de l'instance tags.

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

    Le résultat ressemble à ce qui suit :

    * 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
<
http-server
db-client

  3. Vous pouvez ensuite utiliser cette valeur ETag avec la commande de l'outil curl dans votre requête wait-for-change. Pour utiliser la valeur ETag pour la requête wait-for-change des métadonnées d'instance ou de projet, exécutez la commande suivante :

      curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG" -H "Metadata-Flavor: Google"

    Remplacez les éléments suivants :

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.
    • ETAG : valeur ETag de la clé de métadonnées.

    Dans cet exemple, la commande suivante utilise la valeur ETag pour la clé tags et interroge l'entrée de métadonnées de l'instance.

      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.

VM Windows

Pour obtenir la valeur ETag actuelle d'une clé de métadonnées, procédez comme suit :

  1. Connectez-vous à votre VM Windows.

  2. Envoyez une requête à cette clé et imprimez les en-têtes. Sous Windows, utilisez la commande Invoke-WebRequest : Pour obtenir l'ETag actuel d'une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

      $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
  -Uri http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY)
    


    $value.Headers.ETag

    Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

    • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
    • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
    • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.

    Par exemple, la commande suivante obtient la valeur ETag actuelle pour la clé de métadonnées de l'instance tags.

      PS C:> 
  $value = (Invoke-WebRequest -Headers @{'Metadata-Flavor' = 'Google'} `
  -Uri http://metadata.google.internal/computeMetadata/v1/instance/tags)
    


    $value.Headers.ETag

    Le résultat ressemble à ce qui suit :

      * 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
  <
  http-server
  db-client

  3. Vous pouvez ensuite utiliser cette valeur ETag dans votre requête wait-for-change. Pour utiliser la valeur ETag pour la requête wait-for-change des métadonnées d'instance ou de projet, exécutez la commande suivante :

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&last_etag=ETAG")
  $value

    Remplacez les éléments suivants :

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.
    • ETAG : valeur ETag de la clé de métadonnées.

    Dans cet exemple, la commande suivante utilise la valeur ETag pour la clé tags et interroge l'entrée de métadonnées de l'instance.

      PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e")
  $value

    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.

Python

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

Cet exemple définit l'ETag initial sur 0. Le serveur de métadonnées ne renvoie pas de réponse avec 0 comme valeur 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.

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 wait-for-change expire après un certain nombre de secondes, vous pouvez définir le paramètre timeout_sec. 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.

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.

Linux

  1. Connectez-vous à la VM Linux.

  2. À partir de votre VM Linux, utilisez l'outil curl pour envoyer une requête. Pour exécuter une requête wait-for-change avec une valeur de délai d'inactivité pour une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

      curl "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT" -H "Metadata-Flavor: Google"

    Remplacez les éléments suivants :

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.
    • TIMEOUT : valeur du délai d'expiration.

Par exemple, la commande suivante exécute une requête wait-for-change 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"

Windows

  1. Connectez-vous à votre VM Windows.

  2. À partir de votre VM Windows, exécutez la commande Invoke-RestMethod pour effectuer une requête. Pour exécuter une requête wait-for-change avec une valeur de délai d'inactivité pour une entrée de métadonnées d'instance de VM ou de projet, exécutez la commande suivante :

      $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
          -Uri "http://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY?wait_for_change=true&timeout_sec=TIMEOUT")
  $value

    Remplacez les éléments suivants :

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.
    • TIMEOUT : valeur du délai d'expiration.

Par exemple, la commande suivante exécute une requête wait-for-change qui est définie pour expirer au bout de 360 secondes :

  PS C:> 
  $value = (Invoke-RestMethod -Headers @{'Metadata-Flavor' = 'Google'}
            -Uri "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360")
  $value

Interroger les métadonnées à l'aide du point de terminaison du serveur de métadonnées HTTPS

Le point de terminaison du serveur de métadonnées HTTPS (https://metadata.google.internal/computeMetadata/v1) offre une sécurité supplémentaire pour la transmission des informations entre le serveur de métadonnées et la VM.

Pour utiliser le point de terminaison du serveur de métadonnées HTTPS, examinez les conditions suivantes :

  • Vous devez demander l'accès à l'aperçu du point de terminaison du serveur de métadonnées HTTPS.

  • Une fois votre projet ajouté à la liste d'autorisation, vous pouvez créer la VM. La VM doit répondre aux exigences suivantes :

    • L'environnement invité doit s'exécuter sur la VM.
    • La VM doit être une VM protégée. En effet, le serveur de métadonnées HTTPS nécessite l'utilisation de l'interface UEFI (Unified Extensible Firmware Interface) et du module vTPM (Virtual Trusted Platform Module) pour valider les certificats.

Pour obtenir une présentation de la façon dont les requêtes au point de terminaison du serveur de métadonnées HTTPS sont gérées, consultez la section Point de terminaison du serveur de métadonnées HTTPS. Vous pouvez effectuer les mêmes requêtes sur le serveur de métadonnées, que vous utilisiez le point de terminaison https ou http. Toutefois, pour appeler le point de terminaison https, vous devez spécifier le chemin d'accès aux certificats d'identité du client et, dans certains cas, le certificat racine.

Les commandes suivantes montrent comment interroger le serveur de métadonnées à l'aide du point de terminaison https.

Linux

  1. Connectez-vous à la VM Linux.

  2. À partir de votre VM Linux, utilisez l'outil curl pour envoyer une requête et spécifier le certificat d'identité du client. Vous pouvez également spécifier le certificat racine.

    curl "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY" \
  -E CLIENT_CERTIFICATE \
  [--cacert ROOT_CERTIFICATE] \
  -H "Metadata-Flavor: Google"

    Remplacez les éléments suivants :

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.
    • CLIENT_CERTIFICATE : chemin d'accès au certificat d'identité du client : /run/google-mds-mtls/client.key.
    • Facultatif : ROOT_CERTIFICATE : chemin d'accès au certificat racine : /run/google-mds-mtls/root.crt.

    Par exemple, pour interroger l'image de démarrage d'une VM, exécutez la requête suivante :

    user@myinst:~$ 
curl "https://metadata.google.internal/computeMetadata/v1/instance/image" \
  -E /run/google-mds-mtls/client.key \
  -H "Metadata-Flavor: Google"

    Le résultat ressemble à ce qui suit :

    projects/rhel-cloud/global/images/rhel-8-v20210122

    Si un message d'erreur s'affiche, consultez la documentation de dépannage.

Windows

  1. Connectez-vous à votre VM Windows.

  2. Obtenez le certificat d'identité du client à l'aide de l'une des commandes suivantes :

    • $cert = Get-PfxCertificate -FilePath "C:\ProgramData\Google\Compute Engine\mds-mtls-client.key.pfx"

    • $cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object { $_.Issuer -like "google.internal" }

  3. À partir de votre VM Windows, utilisez la commande Invoke-RestMethod et spécifiez le certificat d'identité du client pour effectuer une requête.

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} -Certificate CLIENT_CERTIFICATE `
          -Uri "https://metadata.google.internal/computeMetadata/v1/PATH_TO_METADATA_ENTRY")
$value

    Remplacez les éléments suivants :

    • CLIENT_CERTIFICATE : chemin d'accès au certificat d'identité du client sur la VM. Il s'agit de la variable $cert définie à l'étape précédente.

    • Remplacez PATH_TO_METADATA_ENTRY par le chemin d'accès à l'instance de VM ou à la clé de métadonnées du projet dont vous souhaitez interroger la valeur. Si la clé se trouve dans un sous-répertoire du répertoire de l'instance ou du projet, veillez à inclure également le sous-répertoire. Exemple :

      • Pour afficher la clé de métadonnées project-id, qui est stockée dans les métadonnées du projet, spécifiez project/project-id.
      • Pour afficher la clé de métadonnées image, qui est stockée dans les métadonnées de l'instance de VM, spécifiez instance/image.
      • Pour afficher les enable-oslogin qui peuvent être stockés dans le sous-répertoire des attributs des métadonnées d'instance de projet ou de VM, spécifiez project/attributes/enable-oslogin ou instance/attributes/enable-oslogin en fonction de votre cas d'utilisation.

    Par exemple, pour interroger l'image de démarrage d'une VM Windows Server 2019, exécutez la requête suivante :

    PS C:\> 
$value = (Invoke-RestMethod `
          -Headers @{'Metadata-Flavor' = 'Google'} -Certificate $cert `
          -Uri "https://metadata.google.internal/computeMetadata/v1/instance/image")
$value

    Le résultat ressemble à ce qui suit :

    projects/windows-cloud/global/images/windows-server-2019-dc-v20210112

Limites

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

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

Codes d'état

Lorsque vous envoyez une requête au serveur de métadonnées, il renvoie des codes d'état HTTP standards pour indiquer le succès ou l'échec de l'opération. Parfois, les conditions du réseau ou les événements hôtes peuvent entraîner l'échec de la requête et le renvoi d'un code d'erreur par le serveur de métadonnées. 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.

Pour obtenir une liste détaillée des codes d'état pouvant être renvoyés, consultez la section Résoudre les problèmes liés aux codes serveur.

Afficher les métadonnées personnalisées de vos VM.

Vous pouvez afficher les valeurs de métadonnées personnalisées de vos VM Compute Engine de l'une des manières suivantes :

Afficher les métadonnées du projet

Pour afficher les métadonnées personnalisées qui s'appliquent à toutes les VM de votre projet, utilisez l'une des méthodes suivantes.

Console

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

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

    La page Métadonnées affiche la liste de toutes les entrées de métadonnées personnalisées de votre projet.

gcloud

Exécutez la commande gcloud compute project-info describe pour interroger les métadonnées du projet :

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

Le résultat ressemble à ce qui suit :

---
fingerprint: HcSFdS_1_1I=
items:
- key: ssh-keys
  value: USERNAME:ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDWZ...
kind: compute#metadata

REST

Pour interroger les métadonnées d'un projet, envoyez une requête GET à la méthode project.get.

Remplacez PROJECT_ID par l'ID du projet.

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

Le résultat ressemble à ce qui suit :

"kind": "compute#project",
"id": "XXXXXXX",
"creationTimestamp": "2018-12-10T08:34:33.616-08:00",
"name": "YOUR_PROJECT",
"commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "XXXXXCdg=",
  "items": [
    {
      "key": "enable-guest-attributes",
      "value": "TRUE"
    },
    {
      "key": "enable-os-inventory",
      "value": "true"
    },
    {
      "key": "enable-osconfig",
      "value": "TRUE"
    },
    {
      "key": "enable-oslogin",
      "value": "TRUE"
    },
    {
      "key": "sshKeys",
      "value": "XXXXX"
    }
  ]
}, ...

Afficher les métadonnées zonales

Pour afficher les métadonnées personnalisées qui s'appliquent à toutes les instances de VM d'une zone spécifique d'un projet, utilisez l'une des méthodes suivantes.

gcloud

Pour interroger les métadonnées zonales personnalisées, utilisez la commande gcloud compute project-zonal-metadata describe.

gcloud compute project-zonal-metadata describe \
    --zone=ZONE \
    --project=PROJECT_ID

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet.
  • ZONE : zone pour laquelle vous souhaitez afficher les métadonnées zonales.

Le résultat ressemble à ce qui suit :

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

REST

Pour interroger les métadonnées zonales personnalisées, envoyez une requête GET à la méthode instanceSettings().get.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet.
  • ZONE : zone pour laquelle vous souhaitez afficher les métadonnées zonales.

Le résultat ressemble à ce qui suit :

{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
    items: {
      "key-1": "value-1",
      "key-2": "value-2"
    }
  }
}

Afficher les métadonnées d'instance

Pour afficher les métadonnées qui s'appliquent à une seule VM de votre projet, utilisez l'une des méthodes suivantes.

Console

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

    Accéder à la page Instances de VM

  2. Cliquez sur le nom de la VM dont vous souhaitez afficher les métadonnées.

    • Clés SSH de cette VM. Dans la section Sécurité et accès, affichez le champ Clés SSH.

      • La valeur None indique qu'aucune clé SSH n'est stockée dans les métadonnées de l'instance.

      • Les autres valeurs indiquent que des clés SSH sont stockées dans les métadonnées de l'instance.

    • Clés SSH d'un projet. Dans la section Sécurité et accès, affichez le champ Bloquer les clés SSH au niveau du projet.

      • La valeur On indique que la valeur de la clé de métadonnées block-project-ssh-keys est TRUE dans les métadonnées d'instance.

      • La valeur Off indique que la valeur de la clé de métadonnées block-project-ssh-keys est FALSE ou que la clé n'est pas définie.

    • Toutes les autres métadonnées personnalisées. Consultez la section Métadonnées personnalisées. Vous voyez toutes les clés et valeurs des métadonnées personnalisées, autres que les métadonnées de clés SSH.

gcloud

Exécutez la commande gcloud compute instances describe pour interroger les métadonnées d'une instance :

gcloud compute instances describe VM_NAME --flatten="metadata[]"

Remplacez VM_NAME par le nom de la VM pour laquelle vous souhaitez rechercher des métadonnées.

Le résultat ressemble à ce qui suit :

---
fingerprint: MTgTJ5m-Cjs=
items:
- key: enable-oslogin
  value: 'true'
kind: compute#metadata

REST

Pour interroger les métadonnées d'une VM spécifique, envoyez une requête GET à la méthode instances.get.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME

Le résultat ressemble à ce qui suit :

......
"metadata": {
"kind": "compute#metadata",
"fingerprint": "XXXXXXVo=",
"items": [
  {
    "key": "enable-oslogin",
    "value": "true"
  }
]
},....

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet
  • ZONE : zone où se trouve la VM
  • VM_NAME : nom de la VM.

Étapes suivantes