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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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
-
Pour afficher des attributs d'invité :
compute.instances.getGuestAttributes
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 :
Accédez à la page Créer une instance dans Google Cloud Console.
Spécifiez les détails de la VM.
Développez la section Options avancées et procédez comme suit :
- Développez la section Gestion.
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
- Key (Clé) :
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 :
Dans Google Cloud Console, accédez à la page Métadonnées.
Cliquez sur Modifier.
Ajoutez une entrée de métadonnées, avec
enable-guest-attributes
comme clé etTRUE
comme valeur. Vous pouvez également définir la valeur surFALSE
pour désactiver la fonctionnalité.Cliquez sur Enregistrer pour appliquer les modifications.
Définissez enable-guest-attributes
dans les métadonnées d'une instance existante :
- Dans Google Cloud Console, accédez à la page Instances de VM.
- Cliquez sur le nom de la VM sur laquelle vous souhaitez définir la valeur des métadonnées.
- En haut de la page des détails de l'instance, cliquez sur Modifier pour modifier les paramètres de l'instance.
- Sous Métadonnées personnalisées, ajoutez une entrée de métadonnées avec
enable-guest-attributes
comme clé etTRUE
comme valeur. Vous pouvez également définir la valeur surFALSE
pour exclure la VM de la fonctionnalité. - 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 dansguest-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 dansguest-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.
Connectez-vous à la VM.
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éesguest-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 dansguest-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éesguest-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 dansguest-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éesguest-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éesguest-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éesguest-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.
Connectez-vous à la VM.
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 dansguest-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 dansguest-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
- Apprenez-en plus sur les métadonnées des VM.