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 de machine virtuelle (VM). N'importe quelle application ou n'importe quel utilisateur de votre instance de VM peut lire et écrire des données dans ces valeurs de métadonnées des attributs d'invité.

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.
  • 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 comme suit :

    Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :

    Console

    Lorsque vous utilisez la console Google Cloud pour accéder aux services et aux API Google Cloud, vous n'avez pas besoin de configurer l'authentification.

    gcloud

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

      gcloud init
    2. Définissez une région et une zone par défaut.

    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

Rôles requis

Les autorisations ou rôles requis varient selon que vous effectuez des tâches au sein de la VM ou en dehors de celle-ci.

Au sein de la VM

Si vous définissez, interrogez ou supprimez les attributs d'invité au sein de la VM, vous n'avez besoin que des rôles et des autorisations nécessaires pour vous connecter à la VM. Tout processus s'exécutant dans l'instance de VM 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.

Pour les lectures et les écritures depuis une VM, le serveur de métadonnées fournit une authentification et une autorisation automatiques au niveau de l'instance. Chaque VM ne peut lire ou écrire que sur son propre serveur de métadonnées. Le serveur de métadonnées d'une VM est inaccessible aux autres VM.

En dehors de la VM

Les rôles et autorisations suivants sont nécessaires pour activer les attributs d'invité ou afficher les attributs d'invité en dehors de la VM à l'aide de la Google Cloud CLI ou de REST. Vous ne pouvez pas définir ou supprimer des attributs d'invité en dehors d'une VM.

Pour vous assurer que votre utilisateur ou votre compte de service dispose des autorisations nécessaires pour activer ou afficher des attributs d'invité, demandez à votre administrateur d'accorder à cet utilisateur ou à ce compte de service le rôle IAM Administrateur d'instances Compute (v1) (roles/compute.instanceAdmin.v1) sur la VM ou sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ce rôle prédéfini contient les autorisations requises pour activer ou afficher des attributs d'invité. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour activer ou afficher des attributs d'invité :

  • Pour activer des attributs d'invité : compute.instances.setMetadata sur la VM ou sur le projet
  • Pour afficher des attributs d'invité : compute.instances.getGuestAttributes sur la VM ou sur le projet

Votre administrateur peut également attribuer ces autorisations à l'utilisateur ou au compte de service avec des rôles personnalisés ou d'autres rôles prédéfinis.

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.

Attributs d'invité et autres services Google Cloud

Les attributs d'invité sont utilisés par d'autres services Google Cloud, comme suit :

  • Sécurité SSH : si les attributs d'invité sont activés et que OS Login est désactivé, l'environnement invité et gcloud CLI utilisent les attributs d'invité pour améliorer la sécurité SSH, en passant par l'API Google pour récupérer les clés d'hôte, avant que vous puissiez vous connecter à votre VM via SSH.
  • VM Manager : l'agent OS Config publie les données du système d'exploitation dans les attributs d'invité.

Pour consulter les entrées de métadonnées stockées par ces services, consultez la page Clés de métadonnées d'attributs d'invité prédéfinis.

Activer les attributs d'invité sur une VM

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 VM individuelles ou dans des métadonnées à l'échelle du projet :

Console

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

  1. Accédez à la page Créer une instance dans Google Cloud Console.

    Accéder à la page Créer une instance

  2. Spécifiez les détails de la VM.

  3. Développez la section Options avancées et procédez comme suit :

    1. Développez la section Gestion.

    2. Dans la section Métadonnées, cliquez sur Ajouter un élément pour ajouter les entrées de métadonnées suivantes :

      • Key (Clé) : enable-guest-attributes
      • Valeur : TRUE

  4. Pour créer la VM, cliquez sur Créer.

Définissez enable-guest-attributes dans les métadonnées à l'échelle du projet afin de l'appliquer à toutes les VM de votre projet :

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

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

  2. Cliquez sur Modifier.

  3. Ajoutez une entrée de métadonnées, avec enable-guest-attributes comme clé et TRUE comme valeur. Vous pouvez également définir la valeur sur FALSE pour désactiver la fonctionnalité.

  4. Cliquez sur Enregistrer pour appliquer les modifications.

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

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

    Accéder à la page Instances de VM

  2. Cliquez sur le nom de la VM sur laquelle vous souhaitez définir la valeur des 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 la VM de la fonctionnalité.
  5. En bas de la page des détails de l'instance, cliquez sur Enregistrer pour appliquer vos modifications à la VM.

gcloud

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

Exécutez la commande gcloud compute instances create dans Google Cloud CLI et définissez enable-guest-attributes=TRUE pour activer les attributs d'invité. Remplacez VM_NAME par le nom de votre VM.

gcloud compute instances create VM_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 VM de votre projet :

Exécutez la commande project-info add-metadata dans Google Cloud CLI 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 Google Cloud CLI et définissez enable-guest-attributes=TRUE pour activer les attributs d'invité. Remplacez VM_NAME par le nom de votre VM.

gcloud compute instances add-metadata VM_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 VM.

Définir des attributs d'invité

Tout processus s'exécutant dans l'instance de VM 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 à la VM ne peuvent pas écrire sur les valeurs de métadonnées des attributs d'invité.

VM Linux

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

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

Remplacez les éléments suivants :

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

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

VM Windows

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

PS C:\> 
$value = (Invoke-RestMethod `
         -Method PUT -Body "VALUE" `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

Remplacez les éléments suivants :

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

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

Obtenir des attributs d'invité

Les utilisateurs ou les comptes de service peuvent lire des attributs d'invité en dehors d'une VM s'ils disposent du rôle requis. N'importe quel utilisateur ou application de la VM peut également lire les valeurs de métadonnées de cette VM 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.

Interroger le serveur de métadonnées

Suivez les instructions ci-dessous pour interroger des attributs d'invité au sein d'une VM.

  1. Connectez-vous à la VM.

  2. Interrogez les attributs d'invité.

    VM Linux

    Par exemple, vous pouvez utiliser une requête curl à partir de votre VM pour lire une valeur à partir du chemin d'accès aux métadonnées guest-attributes :

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

    Remplacez les éléments suivants :

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

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

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

    VM Windows

    Par exemple, vous pouvez utiliser une requête Invoke-RestMethod à partir de votre VM pour lire une valeur à partir du chemin d'accès aux métadonnées guest-attributes :

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

    Remplacez les éléments suivants :

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

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

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

Utiliser la Google Cloud CLI ou REST

Suivez les instructions ci-dessous pour afficher des attributs d'invité en dehors d'une VM.

gcloud

Utilisez la Google Cloud CLI pour lire les valeurs de métadonnées des attributs d'invité pour une VM. Vous pouvez par exemple récupérer toutes les valeurs de la VM en exécutant cette commande :

gcloud compute instances get-guest-attributes VM_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 VM_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 VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

Remplacez les éléments suivants :

  • VM_NAME : nom de la VM à partir de laquelle vous souhaitez lire les valeurs 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 la VM

REST

Utilisez la méthode compute.instances.getguestattributes :

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet.
  • ZONE : zone où se trouve votre VM.
  • VM_NAME : nom de la VM à partir de laquelle vous souhaitez lire les valeurs 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/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

Pour récupérer toutes les clés de chaque espace de noms sur la VM, omettez entièrement NAMESPACE et queryPath :

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_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/VM_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 VM.
  • VM_NAME : nom de la VM à partir de laquelle vous souhaitez lire les valeurs 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é

Suivez les instructions ci-dessous pour supprimer des attributs d'invité au sein d'une VM.

  1. Connectez-vous à la VM.

  2. Supprimez les attributs d'invité.

    VM Linux

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

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

    Remplacez les éléments suivants :

    • NAMESPACE : espace de noms de la clé guest-attributes que vous souhaitez supprimer.
    • KEY : chemin d'accès dans guest-attributes où la valeur est stockée.

    VM Windows

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

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

    Remplacez les éléments suivants :

    • NAMESPACE : espace de noms de la clé guest-attributes que vous souhaitez supprimer.
    • KEY : chemin d'accès dans guest-attributes où la valeur est stockée.

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

Si vous ne souhaitez pas que les VM 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.

Étape suivante