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

Linux Windows

Chaque entrée de métadonnées est stockée sur le serveur de métadonnées en tant que paires clé/valeur. Les clés de métadonnées sont sensibles à la casse. Vos clés peuvent être prédéfinies ou personnalisées.

Les métadonnées personnalisées vous permettent de créer et d'utiliser vos propres paires clé/valeur de métadonnées sur une VM individuelle ou un projet. Vous pouvez ajouter de nouvelles clés de métadonnées personnalisées, mettre à jour les valeurs de vos clés existantes et supprimer toutes les entrées de métadonnées personnalisées lorsque vous n'en avez pas besoin. La définition de métadonnées personnalisées est utile pour transmettre des valeurs arbitraires aux VM d'un projet. Cette opération permet également de créer des scripts de démarrage et d'arrêt.

Ce document fournit des informations sur la façon d'effectuer les opérations suivantes :

Ajoutez ou mettez à jour des métadonnées personnalisées sur des VM.
Supprimez les métadonnées personnalisées des VM.

Avant de commencer

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 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. Installez Google Cloud CLI, puis initialisez-la en exécutant la commande suivante :
```
gcloud init
```
  Remarque : Si vous avez déjà installé gcloud CLI, assurez-vous que vous disposez de la dernière version en exécutant gcloud components update.
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.

Rôles requis

Pour obtenir les autorisations nécessaires pour définir ou supprimer des métadonnées personnalisées sur des VM, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Administrateur d'instances Compute (v1) (roles/compute.instanceAdmin.v1) sur la VM ou le projet
Si vos VM utilisent des comptes de service : Utilisateur du compte de service (roles/iam.serviceAccountUser) sur le compte de service ou le projet

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ces rôles prédéfinis contiennent les autorisations requises pour définir ou supprimer des métadonnées personnalisées sur des VM. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour définir ou supprimer des métadonnées personnalisées sur des VM :

Si vos VM utilisent des comptes de service : iam.serviceAccounts.actAs sur les comptes de service ou le projet
Pour ajouter, mettre à jour ou supprimer des métadonnées personnalisées à l'échelle du projet, procédez comme suit :
- compute.projects.get sur le projet
- compute.projects.setCommonInstanceMetadata sur le projet
Pour ajouter, mettre à jour ou supprimer des métadonnées zonales d'un projet, procédez comme suit :
- compute.instanceSettings.get sur les paramètres d'instance dans la zone requise du projet
- compute.instanceSettings.update sur les paramètres d'instance dans la zone requise du projet
Pour ajouter, mettre à jour ou supprimer des métadonnées d'instance personnalisées, procédez comme suit :
- compute.instances.get sur la VM.
- compute.instances.setMetadata sur la VM.

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

Limites

Compute Engine applique une limite totale combinée de 512 Ko pour toutes les entrées de métadonnées. Les limites de taille maximale sont également appliquées à chaque key et value de la manière suivante:

Chaque métadonnée key est limitée à 128 octets.
Chaque métadonnée key est sensible à la casse.

Pour les métadonnées zonales de projet, Compute Engine ne vous permet pas de créer deux clés de métadonnées distinctes avec la même chaîne, même si elles sont écrites dans des cases différents. Par exemple, si vous disposez d'une clé de métadonnées zonale de projet existante appelée project-zonal-metadata-key, vous ne pouvez pas créer de clés de métadonnées zonales de projet, telles que Project-Zonal-Metadata-Key, PROJECT-ZONAL-METADATA-KEY ou toute autre variante de la même chaîne.
Chaque métadonnée value est limitée à 256 Ko.
Chaque métadonnée value est sensible à la casse, à l'exception des valeurs booléennes.

Par exemple, les clés SSH sont stockées en tant que métadonnées personnalisées sous la clé ssh-keys. Si le contenu des métadonnées ou la valeur (value) de cette clé dépasse la limite de 256 ko, vous ne pouvez pas ajouter de clés SSH. Si vous atteignez cette limite, envisagez de supprimer les clés inutilisées afin de libérer de l'espace de métadonnées pour les nouvelles clés.

En outre, si vous fournissez directement le contenu des scripts de démarrage et d'arrêt, ces contenus peuvent également être stockés en tant que métadonnées personnalisées et être comptabilisés dans ces limites de taille. Pour éviter cette situation, stockez le script de démarrage ou d'arrêt en tant que fichier hébergé sur un emplacement externe, tel que Cloud Storage, puis fournissez l'URL du script de démarrage lors de la création d'une VM. De cette façon, ces fichiers sont téléchargés sur la VM, plutôt que stockés sur le serveur de métadonnées.

Valeurs booléennes

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

État	Autres valeurs
`TRUE`	`Y`, `Yes` et `1`
`FALSE`	`N`, `No` et `0`

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

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

Cette section fournit des informations sur l'ajout de métadonnées personnalisées ou sur la mise à jour de valeurs de métadonnées personnalisées existantes pour vos VM Compute Engine de l'une des manières suivantes :

Définissez des métadonnées personnalisées à l'échelle du projet pour ajouter ou mettre à jour des métadonnées personnalisées pour toutes les VM de votre projet.
Définissez des métadonnées zonales personnalisées d'un projet (bêta) pour ajouter ou mettre à jour des métadonnées personnalisées de projet avec un champ d'application zonal pour les VM du projet.
Définissez des métadonnées d'instance personnalisées pour ajouter ou mettre à jour des métadonnées d'instance personnalisées pour une VM spécifique.

Définir des métadonnées personnalisées à l'échelle d'un projet

Vous pouvez ajouter ou mettre à jour les métadonnées personnalisées de toutes les instances d'un projet à l'aide de la console Google Cloud, de Google Cloud CLI ou de REST.

Suivez les instructions ci-dessous pour appliquer les paramètres de métadonnées à toutes les VM du projet. Par exemple, si vous définissez une paire de métadonnées baz=bat à l'échelle du projet, cette paire est automatiquement appliquée à toutes les VM du projet.

Console

Dans Google Cloud Console, accédez à la page Métadonnées.
Accéder à la page "Métadonnées"
Cliquez sur Modifier.
Ajoutez ou modifiez une entrée de métadonnées.
Enregistrez les modifications.

gcloud

Utilisez la commande project-info add-metadata.

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

Remplacez les éléments suivants :

KEY : nom de votre clé de métadonnées
VALUE : valeur stockée pour cette clé

Exemple

Par exemple, pour définir deux nouvelles entrées foo=bar et baz=bat dans un projet, exécutez la commande suivante :

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

Vous pouvez éventuellement spécifier un ou plusieurs fichiers à partir desquels lire les métadonnées à l'aide de l'option --metadata-from-file.

REST

Facultatif. Pour effectuer un verrouillage optimiste, vous pouvez éventuellement fournir une empreinte.

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

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

Pour obtenir l'empreinte actuelle d'un projet, appelez la méthode project().get.
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
```
Le résultat ressemble à ce qui suit :
```
{
  "name": "myproject",
  "commonInstanceMetadata": {
    "kind": "compute#metadata",
    "fingerprint": "FikclA7UBC0=",
    ...
  }
}
```

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

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata

{
  "fingerprint": "FikclA7UBC0=",
  "items": [
    {
    "key": "foo",
    "value": "bar"
    }
  ]
}

Remplacez PROJECT_ID par l'ID de votre projet.

Définir des métadonnées zonales personnalisées pour le projet

Vous pouvez ajouter ou mettre à jour les entrées de métadonnées zonales de projet pour vos VM de l'une des manières suivantes :

Vous pouvez ajouter des clés de métadonnées personnalisées au niveau zonal d'un projet et définir les valeurs de métadonnées de toutes les VM situées dans une zone spécifique d'un projet.
Vous pouvez mettre à jour les valeurs des clés de métadonnées zonales personnalisées d'un projet pour toutes les VM situées dans une zone spécifique du projet.
Pour les clés de métadonnées de projet qui possèdent déjà des valeurs à l'échelle du projet, vous pouvez les remplacer pour toutes les VM d'une zone spécifique et spécifier ces VM pour utiliser à la place des valeurs zonales de projet.

Éléments à noter avant de définir des métadonnées zonales de projet personnalisées

Le projet et ses entrées de métadonnées zonales sont stockés dans le même répertoire project/. Si vous définissez des valeurs différentes pour les mêmes clés de métadonnées personnalisées pour les VM au niveau du projet et au niveau zonal, les valeurs des métadonnées zonales du projet pour ces clés sont prioritaires sur les métadonnées à l'échelle du projet dans les zones respectives.

Si vous ajoutez une valeur de métadonnées zonale de projet pour une clé de métadonnées ayant déjà une valeur à l'échelle du projet, Compute Engine remplace la valeur à l'échelle du projet pour les VM de la zone spécifiée et met à jour le répertoire /project avec la valeur zonale du projet.
Si vous ajoutez une valeur de métadonnées à l'échelle du projet pour une clé de métadonnées ayant déjà une valeur zonale de projet, rien ne change. Compute Engine conserve la valeur zonale du projet dans le répertoire /project de la zone spécifique.
Si vous ne spécifiez pas de valeur zonale de projet pour une clé de métadonnées personnalisée dans une zone spécifique, mais que la clé a une valeur à l'échelle du projet, vos VM continueront d'avoir les valeurs définies à l'échelle du projet dans ces zones.

Procédure

Vous pouvez ajouter ou mettre à jour les métadonnées personnalisées pour toutes les instances de VM dans une zone spécifique d'un projet à l'aide de Google Cloud CLI ou de REST.

gcloud

Pour ajouter ou mettre à jour des métadonnées zonales d'un projet, utilisez la commande gcloud beta compute project-zonal-metadata add.
```
gcloud beta compute project-zonal-metadata add \
  --zone=ZONE \
  --project=PROJECT_ID  \
  --metadata=KEY1=VALUE1,KEY2=VALUE2,...
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet.
- ZONE : zone dans laquelle vous souhaitez ajouter ou mettre à jour les métadonnées zonales du projet.
- KEY1, KEY2, etc. : clés de métadonnées zonales du projet personnalisées pour lesquelles vous souhaitez ajouter ou mettre à jour des valeurs.
- VALUE1, VALUE2, etc. : valeurs de métadonnées zonales du projet que vous souhaitez définir pour les clés de métadonnées zonales existantes et nouvelles de votre projet. En fonction de votre clé et de votre valeur de métadonnées personnalisées, l'une des situations suivantes se présente :
- Si la clé de métadonnées personnalisée correspondante est une clé existante à l'échelle du projet, Compute Engine remplace la valeur de métadonnées à l'échelle du projet et utilise la valeur zonale du projet pour toutes les VM de la zone spécifiée. Toutes les VM de la zone spécifiée héritent de la nouvelle valeur zonale du projet. Si vous apportez des modifications futures à la valeur définie à l'échelle du projet pour la même clé, ces mises à jour n'affectent pas cette valeur zonale du projet, et les VM de cette zone continuent à avoir la valeur zonale du projet comme métadonnées de leur projet.
- Si la clé de métadonnées personnalisées correspondante est une clé de métadonnées zonale existante du projet et que la valeur de métadonnées spécifiée est une nouvelle valeur, Compute Engine met à jour la valeur zonale du projet pour la clé existante.
- Si la clé de métadonnées personnalisées correspondante est une nouvelle clé ne faisant pas partie des métadonnées zonales existantes à l'échelle du projet, Compute Engine la crée et ajoute cette valeur de métadonnées.
- Si la clé de métadonnées personnalisées correspondante est une clé de métadonnées zonale existante du projet et que la valeur de métadonnées spécifiée est identique à la valeur existante, l'entrée des métadonnées zonales du projet reste inchangée.

Exemple: Ajouter une entrée de métadonnées zonales de projet personnalisée

Par exemple, considérons un projet appelé my-project avec les métadonnées personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"value-1" et "key-2":"value-2"

Pour ajouter "key-4":"value-4" en tant que nouvelle paire de métadonnées zonale de projet personnalisée dans la zone us-central1-a, exécutez la commande suivante

gcloud beta compute project-zonal-metadata add \
    --metadata=key-4=value-4 \
    --project=my-project \
    --zone=us-central1-a

Exemple : Mettre à jour les valeurs d'une entrée de métadonnées zonale de projet personnalisée existante

Prenons l'exemple de projet my-project, qui contient désormais les métadonnées personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"value-1", "key-2":"value-2" et "key-4":"value-4"

Pour mettre à jour les valeurs de métadonnées zonales du projet avec key-1 et key-4 dans la zone us-cerntral1-a avec de nouvelles valeurs, exécutez la commande suivante :

gcloud beta compute project-zonal-metadata add \
    --metadata=key-1=new-value-1,key-4=new-value-4 \
    --project=my-project \
    --zone=us-central1-a

Exemple : remplacer la valeur à l'échelle du projet pour une clé de métadonnées et utiliser une valeur zonale de projet

Prenons l'exemple de projet my-project, qui contient désormais les métadonnées personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"new-value-1", "key-2":"value-2" et "key-4":"new-value-4"

Dans cet exemple de projet, considérons key-3, qui a une valeur de métadonnées value-c à l'échelle du projet. Supposons que vous souhaitiez définir une valeur de métadonnées zonale de projet value-3 pour cette clé pour toutes les VM de la zone us-central1-a. Lorsque vous effectuez l'opération, pour toutes les VM de la zone us-central1-a, Compute Engine remplace les valeurs à l'échelle du projet et utilise les valeurs zonales du projet. Les VM de toutes les autres zones du projet conservent leurs valeurs de métadonnées zonales ou à l'échelle du projet pour key-3.

Pour remplacer la valeur à l'échelle du projet pour key-3 et définir une valeur zonale pour le projet, exécutez la commande suivante :

gcloud beta compute project-zonal-metadata add \
    --metadata=key-3=value-3 \
    --project=my-project \
    --zone=us-central1-a

REST

Obtenez l'empreinte actuelle et affichez les paires clé/valeur existantes pour le projet dans cette zone.

Pour effectuer un verrouillage optimiste, vous devez fournir une empreinte. Une empreinte est une chaîne aléatoire de caractères générée par Compute Engine. L'empreinte change chaque fois que vous envoyez une requête d'ajout, de mise à jour ou de suppression de métadonnées zonales de projet. Si vous fournissez une empreinte non concordante, Compute Engine rejette votre requête.

Si vous ne fournissez pas d'empreinte, une vérification de la cohérence est effectuée et votre requête de mise à jour échoue. Cela permet de n'effectuer qu'une seule requête à la fois, évitant ainsi les conflits. Ce comportement correspond à instances().setMetadata, où une empreinte est toujours requise.

Pour obtenir l'empreinte actuelle des métadonnées zonales du projet, envoyez une requête GET à la méthode instanceSettings().get.
```
GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet.
- ZONE : zone dans laquelle vous souhaitez définir les métadonnées zonales du projet.
Voici un exemple de résultat de cette requête :
```
    {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }
```
Pour ajouter ou mettre à jour les métadonnées zonales du projet, envoyez une requête PATCH à la méthode instanceSettings().patch. Vous devez fournir les éléments suivants avec votre requête :
- Un masque de mise à jour. Utilisez le paramètre de requête update_mask. Le masque de mise à jour doit contenir les clés de métadonnées pour les éléments suivants :
  - Métadonnées zonales du nouveau projet que vous souhaitez ajouter
  - Métadonnées zonales du projet personnalisé existantes dont vous souhaitez mettre à jour les valeurs
  Vous devez ajouter la chaîne metadata.items. en tant que préfixe pour chaque clé, par exemple, metadata.items.key1,metadata.items.key3.
- Dans le corps de la requête, fournissez les informations suivantes :
  - Clés et valeurs des métadonnées des nouvelles métadonnées zonales du projet que vous souhaitez ajouter
  - Clés et valeurs de métadonnées des métadonnées zonales du projet personnalisé que vous souhaitez mettre à jour
  - Valeur d'empreinte actuelle
Attention : Si vous spécifiez des clés de métadonnées zonales de projet personnalisées existantes dans le masque de mise à jour, mais que vous ne les incluez pas dans le corps de la requête, Compute Engine supprime ces entrées de métadonnées zonales du projet. Pour en savoir plus, consultez la page Supprimer les métadonnées zonales d'un projet personnalisé.
```
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
      "KEY1": "VALUE1",
      "KEY2": "VALUE2",
      ...
    }
  }
}
```
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet.
- ZONE : zone dans laquelle vous souhaitez définir les métadonnées zonales du projet.
- PREFIXED_METADATA_KEYS : liste des clés de métadonnées pour le code suivant, où chaque clé est préfixée par la chaîne metadata.items. :
  - Métadonnées zonales du nouveau projet que vous souhaitez ajouter
  - Métadonnées zonales du projet personnalisé existantes dont vous souhaitez mettre à jour les valeurs
  Par exemple, supposons que les clés de métadonnées zonales actuelles de votre projet soient key-1 et key-2. Si vous souhaitez ajouter une clé de métadonnées key-3 et mettre à jour l'une des clés de métadonnées actuelles, key-1, votre masque de mise à jour doit comporter la chaîne suivante :
  
  metadata.items.key1,metadata.items.key3
- FINGER_PRINT : valeur d'empreinte actuelle.
- KEY1, KEY2, etc. : clés de métadonnées zonales du projet personnalisées pour lesquelles vous souhaitez ajouter ou mettre à jour des valeurs. Spécifiez toutes les clés de métadonnées zonales personnalisées du projet que vous avez spécifiées dans le masque de mise à jour.
  
  Attention : Si vous spécifiez des clés de métadonnées zonales de projet personnalisées existantes dans le masque de mise à jour, mais que vous ne les incluez pas dans le corps de la requête, Compute Engine supprime ces entrées de métadonnées zonales du projet. Pour en savoir plus, consultez la page Supprimer les métadonnées zonales d'un projet personnalisé.
- VALUE1, VALUE2, etc. : valeurs de métadonnées zonales du projet que vous souhaitez définir pour les clés de métadonnées zonales existantes et nouvelles de votre projet. En fonction de votre clé et de votre valeur de métadonnées personnalisées, l'une des situations suivantes se présente :
  - Si la clé de métadonnées personnalisée correspondante est une clé existante à l'échelle du projet, Compute Engine remplace la valeur de métadonnées à l'échelle du projet et utilise la valeur zonale du projet pour toutes les VM de la zone spécifiée. Toutes les VM de la zone spécifiée héritent de la nouvelle valeur zonale du projet. Si vous apportez des modifications futures à la valeur définie à l'échelle du projet pour la même clé, ces mises à jour n'affectent pas cette valeur zonale du projet, et les VM de cette zone continuent à avoir la valeur zonale du projet comme métadonnées de leur projet.
  - Si la clé de métadonnées personnalisées correspondante est une clé de métadonnées zonale existante du projet et que la valeur de métadonnées spécifiée est une nouvelle valeur, Compute Engine met à jour la valeur zonale du projet pour la clé existante.
  - Si la clé de métadonnées personnalisées correspondante est une nouvelle clé ne faisant pas partie des métadonnées zonales existantes à l'échelle du projet, Compute Engine la crée et ajoute cette valeur de métadonnées.
  - Si la clé de métadonnées personnalisées correspondante est une clé de métadonnées zonale existante du projet et que la valeur de métadonnées spécifiée est identique à la valeur existante, l'entrée des métadonnées zonales du projet reste inchangée.

Exemple: Ajouter une entrée de métadonnées zonales de projet personnalisée

Par exemple, considérons un projet appelé my-project avec les métadonnées personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"value-1" et "key-2":"value-2"

Pour ajouter "key-4":"value-4" en tant que nouvelle paire de métadonnées zonale d'un projet personnalisé dans la zone us-central1-a, exécutez la requête PATCH suivante :

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-4": "value-4"
    }
  }
}

Exemple : Mettre à jour les valeurs d'une entrée de métadonnées zonale de projet personnalisée existante

Prenons l'exemple de projet my-project, qui contient désormais les métadonnées personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"value-1", "key-2":"value-2" et "key-4":"value-4"

Pour mettre à jour les valeurs de métadonnées zonales key-1 et key-4 du projet dans la zone us-cerntral1-a avec de nouvelles valeurs, exécutez la requête PATCH suivante :

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-1": "new-value-1",
    "key-4": "new-value-4"
    }
  }
}

Exemple : remplacer la valeur à l'échelle du projet pour une clé de métadonnées et utiliser une valeur zonale de projet

Prenons l'exemple de projet my-project, qui contient désormais les métadonnées personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"new-value-1", "key-2":"value-2" et "key-4":"new-value-4"

Pour remplacer la valeur de métadonnées à l'échelle du projet pour key-3 et utiliser plutôt la valeur zonale du projet personnalisé value-3, envoyez la requête PATCH suivante :

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3
{
  "fingerprint": "VlRIl8dx9vk=",
  "metadata": {
  "items": {
    "key-3": "value-3"
    }
  }
}

Définir des métadonnées d'instance personnalisées

Vous pouvez ajouter ou mettre à jour des métadonnées personnalisées pour une seule instance de VM à l'aide de la console Google Cloud, de Google Cloud CLI ou de REST.

Vous pouvez définir les métadonnées d'instance personnalisées de l'une des manières suivantes :

Pour les nouvelles VM, vous pouvez ajouter des métadonnées personnalisées lors de la création de la VM.
Pour les VM existantes, vous pouvez ajouter ou mettre à jour des métadonnées personnalisées lors de l'exécution de la VM.

Ajouter des métadonnées d'instance personnalisées lors de la création d'une VM

Suivez ces instructions pour ajouter des métadonnées sur une instance de VM spécifique au moment de sa création.

Console

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

Accéder à la page Créer une instance
Spécifiez les détails de la VM.
Développez la section Options avancées et procédez comme suit :
1. Développez la section Gestion.
2. Pour ajouter plusieurs paires clé/valeur pour vos métadonnées personnalisées, dans la section Métadonnées, cliquez sur Ajouter un élément.
Pour créer la VM, cliquez sur Créer.

gcloud

Pour définir des métadonnées personnalisées, exécutez la commande gcloud compute instances create avec l'option --metadata.

gcloud compute instances create VM_NAME \
    --metadata=KEY=VALUE

Remplacez les éléments suivants :

VM_NAME : nom de votre VM
KEY : nom de votre clé de métadonnées
VALUE : valeur stockée pour cette clé

Exemple

Par exemple, pour définir une nouvelle clé foo dont la valeur est bar sur une VM nommée example-instance, exécutez la commande suivante :

gcloud compute instances create example-instance \
    --metadata=foo=bar

REST

Utilisez la méthode instances.insert et indiquez les métadonnées personnalisées dans la propriété metadata de la requête :

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

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
  "...": [
    {
    }
    ],
  "metadata": {
    "items": [
      {
        "key": "KEY",
        "value": "VALUE"
      }
    ]
  },
  ..
}

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet.
ZONE : zone dans laquelle créer la VM
MACHINE_TYPE : type de machine prédéfini ou personnalisé pour la nouvelle VM
VM_NAME : nom de la nouvelle VM
KEY : nom de votre clé de métadonnées
VALUE : valeur stockée pour cette clé

Ajouter ou mettre à jour des métadonnées d'instance personnalisées sur une VM existante

Suivez la procédure ci-dessous pour mettre à jour des métadonnées sur une instance de VM spécifique existante.

Console

Dans Google Cloud Console, accédez à la page Instances de VM.
Accéder à la page Instances de VM
Cliquez sur l'instance pour laquelle vous souhaitez mettre à jour les métadonnées.
Cliquez sur le bouton Modifier en haut de la page.
Sous Métadonnées personnalisées, cliquez sur Ajouter un élément ou modifiez les entrées de métadonnées existantes.
Enregistrez les modifications.

gcloud

Les mises à jour des métadonnées de VM avec gcloud CLI s'ajoutent les unes aux autres. Spécifiez uniquement les clés de métadonnées que vous souhaitez ajouter ou modifier. Si une clé que vous avez fournie existe déjà, cette clé est mise à jour avec la nouvelle valeur.

Exécutez la commande instances add-metadata :

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

Remplacez les éléments suivants :

VM_NAME : nom de votre VM
KEY : nom de votre clé de métadonnées
VALUE : valeur stockée pour cette clé

Exemples

Si vous souhaitez ajouter l'entrée foo=bar, exécutez la commande suivante :

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

Pour remplacer l'entrée foo=bar par foo=bat, exécutez la commande suivante :

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

REST

Obtenez l'empreinte actuelle et affichez les paires clé/valeur existantes pour la VM. Pour ce faire, appelez la méthode instances().get.

Une empreinte est une chaîne aléatoire de caractères générée par Compute Engine et utilisée pour effectuer un verrouillage optimal. Pour mettre à jour la VM, vous devez fournir la valeur d'empreinte correspondante. L'empreinte change après chaque requête et si vous fournissez une empreinte non concordante, votre requête est refusée. Cela permet de n'effectuer qu'une seule mise à jour à la fois, évitant ainsi les conflits.
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet.
- ZONE : zone où se trouve votre VM.
- VM_NAME : nom de votre VM
Le résultat ressemble à ce qui suit :
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
      {
        "key": "foo",
        "value": "bar"
      }
    ]
    },
  ...
}
```
Envoyez une requête à la méthode instances().setMetadata. Fournissez la liste des nouvelles valeurs de métadonnées et la valeur fingerprint actuelle.

Si la VM possède des paires clé/valeur existantes que vous souhaitez conserver, vous devez les inclure dans la requête avec les nouvelles paires clé/valeur.

Exemple
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "zhma6O1w2l8=",
"items": [
  {
    "key": "foo",
    "value": "bar"
  },
  {
    "key": "baz",
    "value": "bat"
  }
]
}
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet.
- ZONE : zone où se trouve votre VM.
- VM_NAME : nom de votre VM

Supprimer des métadonnées personnalisées des VM

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

Supprimez les métadonnées personnalisées à l'échelle du projet pour supprimer celles qui ont été définies avec un champ d'application de l'ordre du projet.
Supprimez les métadonnées zonales personnalisées du projet (bêta) pour supprimer les métadonnées définies avec un champ d'application zonal dans ce projet.
Supprimez les métadonnées d'instance personnalisées pour supprimer les métadonnées de VM définies pour une VM spécifique.

Supprimer des métadonnées personnalisées à l'échelle du projet

Vous pouvez supprimer des métadonnées personnalisées à l'échelle du projet à l'aide de la console Google Cloud ou de Google Cloud CLI.

Console

Dans Google Cloud Console, accédez à la page Métadonnées.
Accéder à la page "Métadonnées"
Cliquez sur Modifier en haut de la page.
Dans la section Métadonnées, cliquez sur Supprimer l'élément pour chacune des entrées de métadonnées que vous souhaitez supprimer.
Pour confirmer vos modifications et supprimer les métadonnées personnalisées à l'échelle du projet, cliquez sur Enregistrer.

gcloud

Pour supprimer des métadonnées personnalisées à l'échelle du projet, utilisez la commande gcloud compute project-info remove-metadata.

Si vous souhaitez supprimer les entrées de métadonnées personnalisées pour des clés spécifiques, spécifiez ces clés à l'aide de l'option --keys et excluez les valeurs de ces clés.

gcloud compute project-info remove-metadata \
    --keys=KEY1,KEY2,...

Si vous souhaitez supprimer toutes les métadonnées personnalisées de la VM, spécifiez l'option --all.

gcloud compute project-info remove-metadata \
    --all

Remplacez les éléments suivants :

KEY1, KEY2, etc. : clés de métadonnées d'instance personnalisées que vous souhaitez supprimer.

Supprimer les métadonnées zonales d'un projet personnalisé

Vous pouvez supprimer des métadonnées zonales de projet personnalisées à l'aide de Google Cloud CLI ou de l'API Compute Engine.

gcloud

Pour supprimer les métadonnées zonales d'un projet, exécutez la commande gcloud beta compute project-zonal-metadata remove et spécifiez toutes les clés de métadonnées que vous souhaitez supprimer à l'aide de l'option --keys.

gcloud beta compute project-zonal-metadata remove \
    --project=PROJECT_ID  \
    --zone=ZONE \
    --keys=KEY1,KEY2,...

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet.
ZONE : zone dans laquelle vous souhaitez définir les métadonnées zonales du projet.
KEY1, KEY2, etc. : clés de métadonnées zonales du projet personnalisé que vous souhaitez supprimer.

Après avoir exécuté la commande, si l'une des clés spécifiées dispose de valeurs de métadonnées à l'échelle du projet, les VM de la zone spécifiée héritent de ces valeurs à l'échelle du projet. Si la clé de métadonnées n'a été définie qu'au niveau zonal du projet et qu'il n'y a pas de clé correspondante à l'échelle du projet, les VM perdent ces informations de métadonnées.

Exemple :

Prenons l'exemple d'un projet my-project, qui inclut les métadonnées de projet personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" et "key-4":"new-value-4"

Pour supprimer toutes les métadonnées zonales du projet pour la zone us-central1-a, exécutez la commande suivante.

gcloud beta compute project-zonal-metadata remove \
    --metadata=key-1,key-2,key-3,key-4 \
    --project=my-project \
    --zone=us-central1-a

Une fois la commande exécutée, les VM de la zone us-central1-a possèdent les métadonnées de projet personnalisées suivantes :

"key-1":"value-a"
"key-2":"value-b"
"key-3":"value-c"

REST

Obtenez l'empreinte actuelle et affichez les paires clé/valeur existantes pour le projet dans cette zone.

Pour effectuer un verrouillage optimiste, vous devez fournir une empreinte. Une empreinte est une chaîne aléatoire de caractères générée par Compute Engine. L'empreinte change chaque fois que vous envoyez une requête d'ajout, de mise à jour ou de suppression de métadonnées zonales de projet. Si vous fournissez une empreinte non concordante, Compute Engine rejette votre requête.

Si vous ne fournissez pas d'empreinte, une vérification de la cohérence est effectuée et votre requête de suppression échoue. Cela permet de n'effectuer qu'une seule requête à la fois, évitant ainsi les conflits. Ce comportement correspond à instances().setMetadata, où une empreinte est toujours requise.

Pour obtenir l'empreinte actuelle d'un projet, appelez la méthode instanceSettings().get.
```
GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet.
- ZONE : zone dans laquelle vous souhaitez supprimer les métadonnées zonales du projet.
Voici un exemple de résultat de cette requête :
```
    {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }
```
Pour supprimer des métadonnées zonales de projet personnalisées, exécutez une requête PATCH sur la méthode instanceSettings().patch en excluant les clés de métadonnées pour lesquelles vous souhaitez supprimer les métadonnées zonales du projet, du corps de la requête . Vous devez fournir les éléments suivants avec votre requête :
- Un masque de mise à jour. Utilisez le paramètre de requête update_mask. Le masque de mise à jour doit contenir toutes les clés de métadonnées zonales du projet existantes dont vous souhaitez supprimer les métadonnées. Vous devez ajouter la chaîne metadata.items. comme préfixe pour chaque clé, par exemple, metadata.items.key1,metadata.items.key3.
- Dans le corps de la requête, indiquez uniquement la valeur d'empreinte actuelle. Excluez toutes les clés de métadonnées que vous avez spécifiées dans le masque de mise à jour. Si vous incluez l'une des clés de métadonnées à la fois dans le masque de mise à jour et dans le corps de la requête, Compute Engine ne supprime pas les métadonnées zonales du projet pour ces clés.
```
PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?update_mask=PREFIXED_METADATA_KEYS
{
  "fingerprint": "FINGER_PRINT",
  "metadata": {
    "items": {
    }
  }
}
```
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet.
- ZONE : zone dans laquelle vous souhaitez supprimer les métadonnées zonales du projet.
- PREFIXED_METADATA_KEYS : liste de toutes les clés de métadonnées zonales de projet existantes que vous souhaitez supprimer, où chaque clé est préfixée par la chaîne metadata.items.. Pour garantir le succès de votre requête de suppression, excluez ces clés de métadonnées du corps de la requête. Si vous incluez l'une des clés de métadonnées à la fois dans le masque de mise à jour et dans le corps de la requête, Compute Engine ne supprime pas les métadonnées zonales du projet pour ces clés.
  
  Par exemple, supposons que les clés de métadonnées zonales de votre projet actuel sont key-1, key-2, key-3 et key-4, et que vous souhaitez supprimer les entrées de métadonnées zonales du projet pour key-1 et key-2. Votre masque de mise à jour doit contenir la chaîne suivante :
  
  metadata.items.key1,metadata.items.key2
- FINGER_PRINT : valeur d'empreinte actuelle.

Une fois la requête envoyée, si l'une des clés spécifiées dispose de valeurs de métadonnées à l'échelle du projet, les VM de la zone spécifiée héritent de ces valeurs à l'échelle du projet. Si la clé de métadonnées n'a été définie qu'au niveau zonal pour le projet et qu'il n'y a pas de clé correspondante à l'échelle du projet, les VM perdent ces informations de métadonnées.

Exemple :

Prenons l'exemple d'un projet my-project, qui inclut les métadonnées de projet personnalisées suivantes :

Métadonnées à l'échelle du projet : "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales du projet dans la zone us-central1-a : "key-1":"new-value-1", "key-2":"value-2", "key-3":"value-3" et "key-4":"new-value-4"

Pour supprimer les métadonnées zonales du projet pour key-1 et key-2 dans la zone us-central1-a, exécutez la requête PATCH suivante.

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2
{
  "fingerprint": "FikclA7UBC0=",
  "metadata": {
  "items": {
    }
  }
}

Une fois cette requête transmise, les VM de la zone us-central1-a possèdent les métadonnées de projet personnalisées suivantes. Les VM héritent des valeurs de métadonnées à l'échelle du projet pour key-1 et key-2, mais conservent la valeur zonale du projet pour key-3.

"key-1":"value-a"
"key-2":"value-b"
"key-3":"value-3"

Supprimer des métadonnées d'instance personnalisées

Vous pouvez supprimer des métadonnées d'instance personnalisées à l'aide de la console Google Cloud, de Google Cloud CLI ou de l'API Compute Engine.

Console

Dans Google Cloud Console, accédez à la page Instances de VM.
Accéder à la page Instances de VM
Dans la colonne Nom, cliquez sur le nom de la VM pour laquelle vous souhaitez supprimer des métadonnées.
Cliquez sur Modifier en haut de la page.
Dans la section Métadonnées, cliquez sur Supprimer l'élément pour chacune des entrées de métadonnées que vous souhaitez supprimer.
Pour confirmer vos modifications et supprimer les métadonnées personnalisées de l'instance, cliquez sur Enregistrer.

gcloud

Pour supprimer les métadonnées d'instance personnalisées, exécutez la commande gcloud compute instances remove-metadata.

Si vous souhaitez supprimer les entrées de métadonnées personnalisées pour des clés spécifiques, spécifiez ces clés à l'aide de l'option --keys et excluez les valeurs de ces clés.

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --keys=KEY1,KEY2,...

Si vous souhaitez supprimer toutes les métadonnées personnalisées de la VM, spécifiez l'option --all.

gcloud compute instances remove-metadata VM_NAME \
    --zone=ZONE  \
    --all

Remplacez les éléments suivants :

PROJECT_ID : ID de votre projet.
ZONE : zone de votre VM
VM_NAME : nom de votre VM
KEY1, KEY2, etc. : clés de métadonnées d'instance personnalisées que vous souhaitez supprimer.

REST

Obtenez l'empreinte actuelle et affichez les paires clé/valeur existantes pour la VM. Pour ce faire, appelez la méthode instances().get.

Une empreinte est une chaîne aléatoire de caractères générée par Compute Engine et utilisée pour effectuer un verrouillage optimal. Pour mettre à jour la VM, vous devez fournir la valeur d'empreinte correspondante. L'empreinte change après chaque requête et si vous fournissez une empreinte non concordante, votre requête est refusée. Cela permet de n'effectuer qu'une seule mise à jour à la fois, évitant ainsi les conflits.
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet.
- ZONE : zone de votre VM
- VM_NAME : nom de votre VM
Le résultat ressemble à ce qui suit :
```
{
  ...
  "name": "example-instance",
  "metadata": {
    "kind": "compute#metadata",
    "fingerprint": "zhma6O1w2l8="
    "items": [
    {
      "key": "key-1",
      "value": "value-1"
    }
    {
      "key": "key-2",
      "value": "value-2"
    }
    ]
  },
  ...
}
```
Envoyez une requête à la méthode instances().setMetadata. Pour que votre requête aboutisse, vous devez inclure la valeur d'empreinte actuelle des métadonnées.
- Pour supprimer toutes les paires clé/valeur des métadonnées personnalisées d'une VM, dans la propriété items, excluez les clés de métadonnées pour lesquelles vous souhaitez supprimer les valeurs de métadonnées.
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "FINGER_PRINT"
"items": [
  {
    "key": "KEY1"
    "value": "VALUE1"
  }
  {
    "key": "KEY2"
    "value": "VALUE2"
  }
  ...
]
}
```
- Pour supprimer toutes les métadonnées d'instance personnalisées sur la VM, excluez la propriété items.
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": FINGER_PRINT
}
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet.
- ZONE : zone de votre VM
- VM_NAME : nom de votre VM
- FINGER_PRINT : valeur d'empreinte actuelle.
- KEY1, KEY2, etc. : clés de métadonnées d'instance personnalisées que vous souhaitez supprimer.
- VALUE1, VALUE2, etc. : valeurs des clés de métadonnées d'instance personnalisées que vous souhaitez supprimer.

Étapes suivantes

Apprenez-en plus sur les métadonnées des VM.
Découvrez comment afficher et interroger des métadonnées.
Obtenez plus d'informations sur l'exécution des scripts de démarrage ou des scripts d'arrêt sur le serveur de métadonnées.