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 paire clé/valeur. Les clés de métadonnées sont sensibles à la casse. Vos clés peuvent être des clés de métadonnées 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 sur 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 :

Ajouter ou mettre à jour des métadonnées personnalisées sur des VM
Supprimer des 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 :

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
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

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 de projet personnalisées, 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 personnalisées, 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. Des 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, 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 personnalisée existante pour des métadonnées zonales appelées project-zonal-metadata-key, vous ne pouvez pas créer de clés de métadonnées 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 d'un 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 pour ajouter ou mettre à jour des métadonnées personnalisées 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 de projet personnalisées

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 de projet, cette paire est automatiquement appliquée à toutes les VM du projet.

Console

Dans la console Google Cloud, accédez à la page Métadonnées.
Accéder à la page "Métadonnées personnalisées"
Cliquez sur Modifier en haut de la page.
Pour ajouter des entrées de métadonnées de projet personnalisées, procédez comme suit :
1. Accédez au bas de la page, puis cliquez sur Ajouter un élément.
2. Dans le champ Clé, saisissez le nom de votre clé de métadonnées personnalisées.
3. Dans le champ Valeur, saisissez la valeur des métadonnées personnalisées du projet.
4. Facultatif. Pour ajouter d'autres entrées de métadonnées de projet personnalisées, répétez les étapes précédentes pour chaque entrée de métadonnées que vous souhaitez ajouter.
5. Pour terminer d'ajouter des entrées de métadonnées de projet personnalisées, cliquez sur Enregistrer.
Pour modifier des entrées de métadonnées de projet personnalisées existantes, procédez comme suit:
1. Accédez à l'entrée de métadonnées que vous souhaitez modifier.
2. Pour mettre à jour le nom d'une clé de métadonnées personnalisées spécifique, saisissez le nouveau nom dans le champ Clé de cette entrée.
3. Pour mettre à jour la valeur d'une entrée de métadonnées de projet personnalisées, saisissez la nouvelle valeur dans le champ Valeur de cette entrée.
4. Facultatif. Pour supprimer une entrée de métadonnées de projet personnalisées spécifique, cliquez sur l'icône de suppression à côté de l'entrée de métadonnées.
5. Pour modifier plusieurs entrées de métadonnées de projet personnalisées, répétez les étapes précédentes pour chaque entrée de métadonnées que vous souhaitez modifier.
6. Pour terminer de modifier les entrées de métadonnées personnalisées de votre projet, cliquez sur Enregistrer.

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

Lorsque vous définissez des métadonnées zonales personnalisées, vous ajoutez ou mettez à jour les entrées de métadonnées zonales pour vos VM dans une zone spécifique d'un projet. Vous pouvez effectuer les opérations suivantes en définissant des métadonnées zonales personnalisées:

Créer des clés de métadonnées personnalisées pour une zone spécifique d'un projet et définir des métadonnées pour toutes les VM de cette zone dans ce projet.
Mettre à jour les valeurs des entrées de métadonnées zonales personnalisées existantes pour toutes les VM d'une zone spécifique d'un projet.
Pour les clés de métadonnées personnalisées existantes dotées de valeurs de métadonnées de projet, remplacez ces valeurs de métadonnées de projet dans des zones spécifiques et définissez plutôt des métadonnées zonales. Une fois que vous avez défini des métadonnées zonales pour ces clés dans une zone spécifique, toutes les VM de cette zone dans ce projet utilisent les valeurs de métadonnées zonales de ces clés.

Points à noter avant de définir des métadonnées zonales 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 de projet, Compute Engine remplace la valeur de 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 de métadonnées zonale, rien ne change. Compute Engine conserve la valeur des métadonnées zonales dans le répertoire /project de la zone spécifique.
Si vous ne spécifiez pas de valeur de métadonnées zonale de projet pour une clé de métadonnées personnalisée dans une zone spécifique, mais que la clé a une valeur de métadonnées de projet, vos VM continueront d'avoir les valeurs de métadonnées de projet dans ces zones.

Procédure

Vous pouvez ajouter ou mettre à jour les métadonnées zonales personnalisées 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 personnalisées, exécutez la commande gcloud compute project-zonal-metadata add.
```
gcloud 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 personnalisées pour lesquelles vous souhaitez ajouter ou mettre à jour des valeurs de métadonnées zonales.
- VALUE1, VALUE2, etc. : valeurs de métadonnées zonales que vous souhaitez définir pour vos clés de métadonnées personnalisées existantes et nouvelles. 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ées correspondante est une clé existante contenant des métadonnées de projet, Compute Engine remplace la valeur de métadonnées du projet de la clé par la valeur de métadonnées zonale spécifiée dans la zone spécifiée. Toutes les VM de la zone spécifiée dans le projet héritent de ces métadonnées zonales nouvellement spécifiées pour cette clé et les VM des autres zones continuent de conserver leurs valeurs de métadonnées zonales ou de projet dominantes. Si vous effectuez des mises à jour ultérieures de la valeur de métadonnées du projet pour cette clé, les VM de cette zone du projet ne sont pas affectées et continuent à utiliser la valeur de métadonnées zonales pour cette clé.
- Si la clé de métadonnées personnalisées correspondante est une nouvelle clé de métadonnées qui n'est pas utilisée pour les métadonnées de projet ou zonales existantes, Compute Engine crée la clé de métadonnées personnalisées et définit cette valeur comme métadonnées zonales dans la zone spécifiée.
- Si la clé de métadonnées personnalisées correspondante est une clé de métadonnées existante avec une valeur de métadonnées zonale dans la zone spécifiée:
  - Si la valeur de métadonnées spécifiée est différente de la valeur existante, Compute Engine met à jour l'entrée de métadonnées zonales avec la nouvelle valeur.
  - Si la valeur de métadonnées spécifiée est identique à la valeur existante, l'entrée de métadonnées zonale reste inchangée.

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

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

Métadonnées du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 zonales personnalisées dans la zone us-central1-a, exécutez la commande suivante :

gcloud 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 personnalisée existante

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

Métadonnées du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 avec key-1 et key-4 dans la zone us-cerntral1-a avec de nouvelles valeurs, exécutez la commande suivante :

gcloud 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 de métadonnées du projet pour une clé et utiliser une valeur de métadonnées zonale

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

Métadonnées du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 de projet. Supposons que vous souhaitiez définir une valeur de métadonnées zonales value-3 pour cette clé pour toutes les VM de la zone us-central1-a. Lorsque vous exécutez l'opération, pour toutes les VM de la zone us-central1-a, Compute Engine remplace les valeurs de métadonnées du projet et utilise les valeurs de métadonnées zonales. Les VM de toutes les autres zones du projet conservent leur projet ou les valeurs de métadonnées zonales prédominantes pour key-3.

Pour remplacer la valeur de métadonnées du projet pour key-3 et définir une valeur de métadonnées zonale, exécutez la commande suivante:

gcloud 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 effectuez une requête d'ajout, de mise à jour ou de suppression de métadonnées zonales. Si vous fournissez une empreinte non concordante, Compute Engine rejette la requête.

Si vous ne fournissez pas d'empreinte, une vérification de 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, 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 dans laquelle vous souhaitez définir les métadonnées zonales.
Voici un exemple de résultat de cette requête :
```
    {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
        ...
      }
    }
```
Pour ajouter ou mettre à jour les métadonnées zonales, 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 :
  - Nouvelles métadonnées zonales que vous souhaitez ajouter
  - Métadonnées zonales personnalisé existantes dont vous souhaitez mettre à jour les valeurs
  Vous devez ajouter la chaîne metadata.items. comme préfixe pour chaque clé, par exemple, metadata.items.key1,metadata.items.key3.
  
  Important : Le masque de mise à jour doit être en minuscules.
- Dans le corps de la requête, fournissez les informations suivantes :
  - Clés et valeurs de métadonnées des nouvelles métadonnées zonales personnalisées que vous souhaitez ajouter
  - Clés et valeurs de métadonnées des métadonnées zonales personnalisées existantes que vous souhaitez mettre à jour
  - Valeur d'empreinte actuelle
Attention : Si vous spécifiez des clés de métadonnées zonales 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. Pour en savoir plus, consultez la page Supprimer les métadonnées zonales personnalisées.
```
PATCH https://compute.googleapis.com/compute/v1/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.
- 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. :
  - Nouvelles métadonnées zonales que vous souhaitez ajouter
  - Métadonnées zonales personnalisé existantes dont vous souhaitez mettre à jour les valeurs
  Par exemple, supposons que vos clés de métadonnées zonales actuelles dans une zone spécifique soient key-1 et key-2. Si vous souhaitez ajouter une clé key-3 pour les métadonnées zonales dans cette zone et mettre à jour les métadonnées zonales de l'une des clés existantes, 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 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 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 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. Pour en savoir plus, consultez la page Supprimer les métadonnées zonales personnalisées.
- VALUE1, VALUE2, etc. : valeurs de métadonnées zonales que vous souhaitez définir pour vos clés de métadonnées personnalisées existantes et nouvelles. 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ées correspondante est une clé existante contenant des métadonnées de projet, Compute Engine remplace la valeur de métadonnées du projet de la clé par la valeur de métadonnées zonale spécifiée dans la zone spécifiée. Toutes les VM de la zone spécifiée dans le projet héritent de ces métadonnées zonales nouvellement spécifiées pour cette clé et les VM des autres zones continuent de conserver leurs valeurs de métadonnées zonales ou de projet dominantes. Si vous effectuez des mises à jour ultérieures de la valeur de métadonnées du projet pour cette clé, les VM de cette zone du projet ne sont pas affectées et continuent à utiliser la valeur de métadonnées zonales pour cette clé.
  - Si la clé de métadonnées personnalisées correspondante est une nouvelle clé de métadonnées qui n'est pas utilisée pour les métadonnées de projet ou zonales existantes, Compute Engine crée la clé de métadonnées personnalisées et définit cette valeur comme métadonnées zonales dans la zone spécifiée.
  - Si la clé de métadonnées personnalisées correspondante est une clé de métadonnées existante avec une valeur de métadonnées zonale dans la zone spécifiée:
  - Si la valeur de métadonnées spécifiée est différente de la valeur existante, Compute Engine met à jour l'entrée de métadonnées zonales avec la nouvelle valeur.
  - Si la valeur de métadonnées spécifiée est identique à la valeur existante, l'entrée de métadonnées zonale reste inchangée.

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

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

Métadonnées du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 personnalisées dans la zone us-central1-a, exécutez la requête PATCH suivante :

PATCH https://compute.googleapis.com/compute/v1/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 personnalisée existante

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

Métadonnées du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 dans la zone us-cerntral1-a avec de nouvelles valeurs, exécutez la requête PATCH suivante :

PATCH https://compute.googleapis.com/compute/v1/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 de métadonnées du projet pour une clé et définir une valeur de métadonnées zonale

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

Métadonnées du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 du projet pour key-3 et utiliser plutôt la valeur de métadonnées zonale value-3, exécutez la requête PATCH suivante:

PATCH https://compute.googleapis.com/compute/v1/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 lorsque la VM est en cours d'exécution.

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

Suivez la procédure ci-dessous 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 les métadonnées personnalisées des VM

Cette section fournit des informations sur la suppression des entrées de métadonnées personnalisées pour vos VM Compute Engine de l'une des manières suivantes:

Supprimez les métadonnées personnalisées d'un projet pour supprimer les métadonnées personnalisées définies pour toutes les VM d'un projet.
Supprimez les métadonnées zonales personnalisées pour supprimer les métadonnées personnalisées définies pour toutes les VM d'une zone spécifique d'un projet.
Supprimez les métadonnées d'instances personnalisées pour supprimer les métadonnées de VM définies pour une VM spécifique.

Supprimer des métadonnées de projet personnalisées

Vous pouvez supprimer des métadonnées de projet personnalisées à 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.
Accédez à l'entrée de métadonnées que vous souhaitez supprimer, puis cliquez sur le bouton de suppression situé à côté de cette entrée.

Répétez cette étape pour chaque entrée de métadonnées que vous souhaitez supprimer.
Pour terminer la suppression des entrées de métadonnées personnalisées du projet, cliquez sur Enregistrer.

gcloud

Pour supprimer des métadonnées de projet personnalisées, 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 personnalisées

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

gcloud

Pour supprimer des métadonnées zonales personnalisées, exécutez la commande gcloud 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 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 supprimer les métadonnées zonales.
KEY1, KEY2, etc. : clés de métadonnées zonales personnalisées 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 de projet, les VM de la zone spécifiée héritent de ces valeurs de métadonnées de projet. Si l'entrée de métadonnées n'a été définie qu'au niveau zonal et qu'il n'y a pas de valeur de métadonnées de projet correspondante pour cette clé, les VM de cette zone 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 du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 de la zone us-central1-a, exécutez la commande suivante.

gcloud 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 entrées de 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 effectuez une requête d'ajout, de mise à jour ou de suppression de métadonnées zonales. Si vous fournissez une empreinte non concordante, Compute Engine rejette la requête.

Si vous ne fournissez pas d'empreinte, une vérification de cohérence est effectuée et votre requête de suppression n'aboutit pas. 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.
Voici un exemple de résultat de cette requête :
```
    {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
        ...
      }
    }
```
Pour supprimer des métadonnées zonales 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 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 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.
  
  Important : Le masque de mise à jour doit être en minuscules.
- Dans le corps de la requête, indiquez uniquement la valeur actuelle de l'empreinte. Excluez toutes les clés de métadonnées personnalisé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 dans le masque de mise à jour et dans le corps de la requête, Compute Engine ne supprime pas les métadonnées zonales de 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.
- PREFIXED_METADATA_KEYS: liste de toutes les clés de métadonnées personnalisées existantes pour lesquelles vous souhaitez supprimer des métadonnées zonales, où chaque clé est préfixée par la chaîne metadata.items.. Pour vous assurer que votre requête de suppression aboutit, 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 dans le masque de mise à jour et dans le corps de la requête, Compute Engine ne supprime pas les métadonnées zonales de ces clés.
  
  Par exemple, supposons que vos clés de métadonnées actuelles avec des métadonnées zonales soient key-1, key-2, key-3 et key-4, et que vous souhaitez supprimer les entrées de métadonnées zonales pour key-1 et key-2, votre masque de mise à jour doit comporter la chaîne suivante:
  
  metadata.items.key1,metadata.items.key2
- FINGER_PRINT : valeur d'empreinte actuelle.

Après avoir envoyé la requête, si l'une des clés spécifiées dispose de valeurs de métadonnées de projet, les VM de la zone spécifiée héritent de ces valeurs de métadonnées de projet. Si la clé de métadonnées n'a été définie qu'au niveau zonal et qu'il n'y a pas de valeur de métadonnées de projet correspondante pour cette clé, les VM de cette zone 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 du projet: "key-1":"value-a", "key-2":"value-b" et "key-3":"value-c"
Métadonnées zonales 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 pour key-1 et key-2 dans la zone us-central1-a, 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-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 personnalisées suivantes. Les VM héritent des valeurs de métadonnées du projet pour key-1 et key-2, mais conservent les métadonnées zonales pour key-3 et key-4.

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

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 les 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 d'instance personnalisées, cliquez sur Enregistrer.

gcloud

Pour supprimer des métadonnées d'instance personnalisées, utilisez 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. Vous devez inclure la valeur actuelle d'empreinte des métadonnées pour que votre requête aboutisse.
- 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'instances personnalisées de la VM, excluez complètement 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.