Configurer des métadonnées avec état dans des groupes d'instances gérés (MIG)

L'intérêt des métadonnées d'instance est de définir des propriétés pour vos applications et de communiquer avec elles à travers le serveur de métadonnées. Par exemple, vous pouvez utiliser des métadonnées pour configurer l'identité de l'instance de machine virtuelle (VM), des variables d'environnement, des informations sur l'architecture du cluster ou encore la plage de données dont une VM est responsable.

En configurant des métadonnées avec état dans un groupe d'instances géré (MIG), vous vous assurez que les métadonnées spécifiques à l'instance sont conservées lors des opérations d'autoréparation, de mise à jour et de recréation des instances gérées.

Vous configurez les métadonnées avec état individuellement pour les instances de VM d'un MIG en les définissant dans des configurations par instance et en appliquant la configuration. Vous pouvez définir une configuration par instance lors de la création de l'instance ou sur des instances gérées existantes. Une fois la configuration par instance appliquée, le groupe d'instances géré stocke les métadonnées avec état dans le champ État préservé issu de la configuration (preservedStateFromConfig) d'une instance gérée.

Avant de commencer

Consultez les pages expliquant quand utiliser des groupes d'instances gérés avec état et le fonctionnement des groupes d'instances gérés (MIG) avec état.
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:
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.

Limites

Un MIG avec des métadonnées avec état présente les limites suivantes :

Un MIG doté d'une configuration avec état (un MIG avec état) présente les limites suivantes :

Vous ne pouvez pas utiliser l'autoscaling si votre MIG dispose d'une configuration avec état.
Si vous souhaitez utiliser des mises à jour progressives automatiques, vous devez définir la méthode de remplacement sur RECREATE.
Pour les MIG régionaux avec état, vous devez désactiver la redistribution proactive (définissez le type de redistribution sur NONE) pour empêcher la suppression d'instances avec état lors de redistributions interzones automatiques.
Si vous utilisez une configuration sur toutes les instances pour remplacer les propriétés d'un modèle d'instance, vous ne pouvez pas spécifier ces propriétés à la fois dans une configuration par instance et dans une configuration sur toutes les instances du groupe.
Lorsque vous supprimez une instance de manière définitive (manuellement ou par redimensionnement), le MIG ne conserve pas les métadonnées avec état de cette instance.

Définir des métadonnées avec état à la création d'une instance

Vous pouvez définir des métadonnées avec état lorsque vous créez manuellement une instance au sein d'un MIG. Cela est utile pour migrer une application avec état hébergée sur des VM autonomes vers un MIG avec état, ainsi que lors de la création d'instances avec état.

Lorsque vous créez manuellement une instance au sein d'un MIG et que vous fournissez des métadonnées avec état, le MIG effectue les tâches suivantes :

Il crée une instance gérée basée sur le modèle d'instance et portant le nom d'instance fourni.
Il crée une configuration par instance à partir des métadonnées avec état fournies et définit ces métadonnées sur l'instance.
Il stocke les métadonnées avec état dans l'état préservé issu de la configuration (preservedStateFromConfig) de l'instance gérée associée.

gcloud

Pour créer une instance gérée portant un nom personnalisé et définir des métadonnées avec état pour cette VM, utilisez la commande gcloud compute instance-groups managed create-instance avec l'option --stateful-metadata.

gcloud compute instance-groups managed create-instance NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...]

Remplacez les éléments suivants :

NAME : nom du MIG dans lequel créer l'instance.
INSTANCE_NAME : nom de l'instance à créer.
KEY et VALUE : paires clé/valeur de métadonnées avec état à définir individuellement pour les instances en plus des métadonnées définies dans le modèle d'instance.
- En cas de conflit, les valeurs de clé que vous définissez ici sont prioritaires sur les valeurs de clé issues du modèle d'instance.

Exemple

Vous devez déployer un cluster de nœuds, example-cluster, qui peut fonctionner dans l'un des deux modes suivants : active ou standby. Vous définissez le mode individuellement pour chaque VM du cluster à l'aide de métadonnées, par exemple : mode:active. Vous configurez également le niveau de détail de la journalisation pour chaque nœud à l'aide d'une clé de métadonnées logging pouvant être définie sur basic ou elaborate. L'application hébergée sur le nœud est configurée à l'aide des valeurs issues des métadonnées d'instance.

Pour créer un nœud actif nommé node-12 et avec une journalisation détaillée ("elaborate"), exécutez la commande suivante :

gcloud compute instance-groups managed create-instance example-cluster \
  --instance node-12 \
  --stateful-metadata mode=active,logging=elaborate

La commande crée une VM node-12 dans le MIG example-cluster et définit deux paires de métadonnées clé/valeur, mode:active et logging:elaborate, pour la nouvelle instance.

Terraform

Pour créer une instance gérée portant un nom personnalisé et définir des métadonnées avec état pour cette VM, utilisez la ressource google_compute_per_instance_config.

L'exemple suivant utilise un MIG zonal. Si vous ne disposez pas encore d'un MIG zonal, créez un MIG zonal avec des VM limitées à une seule zone.

resource "google_compute_per_instance_config" "default" {
  instance_group_manager = google_compute_instance_group_manager.default.name
  zone                   = google_compute_instance_group_manager.default.zone
  name                   = "node-12"
  preserved_state {
    metadata = {
      mode    = "active"
      logging = "elaborate"
    }
  }
}

Pour savoir comment appliquer ou supprimer une configuration Terraform, consultez la page Commandes Terraform de base.

REST

Pour créer dans un MIG une ou plusieurs instances gérées, dotées de noms de VM personnalisés et sur lesquelles sont définies individuellement des métadonnées avec état, utilisez la méthode instanceGroupManagers.createInstances. Pour un MIG régional, utilisez la méthode regionInstanceGroupManagers.createInstances.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/createInstances
{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY" : "VALUE",
          ...
        }
      }
    },
    ...
  ]
}

Remplacez les éléments suivants :

PROJECT_ID : ID du projet pour la requête.
ZONE : zone où se trouve le MIG (s'applique à un MIG zonal).
- Pour un MIG régional, remplacez zones/ZONE par regions/REGION et spécifiez la région du MIG.
NAME : nom du MIG dans lequel créer l'instance.
INSTANCE_NAME : nom de l'instance à créer.
KEY et VALUE : paires clé/valeur de métadonnées avec état à définir individuellement pour les instances en plus des métadonnées définies dans le modèle d'instance.
- En cas de conflit, les valeurs de clé que vous définissez ici sont prioritaires sur les valeurs de clé issues du modèle d'instance.

Exemple

Pour créer un nœud actif nommé node-12 et avec une journalisation détaillée ("elaborate"), exécutez la méthode suivante :

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/createInstances

{
  "instance": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode":"active",
          "logging":"elaborate"
        }
      }
    }
  ]
}

La méthode crée une VM node-12 dans le MIG example-cluster et définit deux paires de métadonnées clé/valeur, mode:active et logging:elaborate, pour la nouvelle instance.

Définir, modifier et supprimer des métadonnées avec état individuellement pour des instances de VM existantes

Vous définissez, modifiez ou supprimez les métadonnées avec état d'une instance existante au sein d'un groupe d'instances géré en définissant sa configuration sur une configuration par instance associée, puis en appliquant la configuration par mise à jour de l'instance.

gcloud

Pour configurer des métadonnées avec état individuellement pour une instance de VM au sein d'un groupe d'instances géré, définissez ou supprimez des métadonnées avec état dans la configuration par instance associée. Si vous appliquez simultanément la configuration à l'instance (--update-instance), vous pouvez choisir de maintenir l'instance en cours d'exécution, de la redémarrer ou de la recréer. Si vous n'appliquez pas la configuration (--no-update-instance), vos modifications ne prendront effet qu'après la recréation ou la mise à jour de l'instance.

Si aucune configuration par instance n'existe pour une instance donnée, exécutez la commande gcloud compute instance-groups managed instance-configs create avec l'une des options suivantes :

gcloud compute instance-groups managed instance-configs create NAME \
  --instance INSTANCE_NAME \
  --stateful-metadata KEY=VALUE[,KEY=VALUE,...] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

Si une configuration par instance existe déjà pour une instance donnée, utilisez la commande gcloud compute instance-groups managed instance-configs update avec :

L'option --stateful-metadata pour définir ou modifier les métadonnées, ou
L'option --remove-stateful-metadata pour supprimer les métadonnées avec état spécifiques à une instance

gcloud compute instance-groups managed instance-configs update NAME \
  --instance INSTANCE_NAME \
  [--stateful-metadata KEY=VALUE[,KEY=VALUE,...]] \
  [--remove-stateful-metadata KEY[,KEY,...]] \
  [--no-update-instance | --update-instance] \
  [--instance-update-minimal-action MINIMAL_ACTION]

Remplacez les éléments suivants :

NAME : nom du groupe d'instances géré.
INSTANCE_NAME : nom de l'instance pour laquelle configurer des métadonnées avec état.
KEY=VALUE : paires clé/valeur de métadonnées avec état à définir individuellement pour les instances en plus des métadonnées définies dans le modèle d'instance. En cas de conflit, les valeurs de clé que vous définissez ici sont prioritaires sur les valeurs de clé issues du modèle d'instance.
KEY : clés de métadonnées avec état spécifiques à l'instance, à supprimer de la configuration par instance.
- Si aucune valeur n'est définie par le modèle d'instance pour une clé donnée, la paire clé/valeur est entièrement supprimée de l'instance lorsque la modification est appliquée.
- Si une valeur est définie par le modèle d'instance pour une clé donnée, la valeur du modèle d'instance est définie pour l'instance lorsque la modification est appliquée.
MINIMAL_ACTION : effectue au moins l'action spécifiée lorsque la mise à jour de la configuration par instance est effectivement appliquée à l'instance. Une option MINIMAL_ACTION ne peut être définie que lorsque l'option --update-instance est utilisée. La valeur doit correspondre à l'un des éléments suivants :
- none : aucune action.
- refresh : appliquer les mises à jour qu'il est possible d'appliquer sans arrêter l'instance.
- restart : arrêter l'instance, puis la redémarrer.
- replace : recréer l'instance.
Si cet élément n'est pas spécifié, l'action la moins perturbatrice requise par la mise à jour est utilisée.

Exemple

Vous disposez d'un cluster de nœuds, example-cluster, qui peut fonctionner dans l'un des deux modes suivants : active ou standby. Vous définissez le mode individuellement pour chaque VM du cluster à l'aide de métadonnées, par exemple : mode:active. Vous configurez également le niveau de détail de la journalisation pour chaque nœud à l'aide d'une clé de métadonnées logging pouvant être définie sur basic ou elaborate. L'application sur chaque nœud utilise les valeurs des métadonnées de l'instance.

Le modèle d'instance définit les métadonnées mode:active et logging:basic comme valeurs à utiliser par défaut pour toutes les instances. Vous avez défini logging:elaborate dans une configuration par instance pour la VM node-12 du cluster. Vous souhaitez maintenant passer node-12 en mode veille et basculer la journalisation sur basic pour cette VM.

Pour mettre l'instance node-12 en veille et passer sa journalisation en version de base, exécutez la commande suivante :

gcloud compute instance-groups managed instance-configs update example-cluster \
  --instance node-12 \
  --stateful-metadata mode=standby \
  --remove-stateful-metadata logging

La commande :

Elle définit la métadonnée mode:standby dans la configuration par instance associée à la VM node-12, au sein du groupe d'instances géré example-cluster.
Elle supprime la métadonnée logging:elaborate de la configuration par instance de l'instance node-12.
Applique la modification de configuration par instance à la VM node-12 :
- Définit les métadonnées mode:standby selon la configuration.
- Définit les métadonnées logging:basic du modèle d'instance, car la valeur de la clé logging n'est plus définie par la configuration par instance.
La modification est appliquée immédiatement à la VM, car l'option --no-update-instance a été omise.
La VM continue de s'exécuter pendant la mise à jour, car l'option --instance-update-minimal-action a été omise et c'est donc l'action la moins perturbatrice qui est choisie par défaut pour la mise à jour : refresh.

REST

Pour configurer des métadonnées avec état individuellement pour des instances de VM existantes au sein d'un groupe d'instances géré, définissez ou supprimez les métadonnées dans les configurations par instance associées. Ensuite, mettez à jour l'instance pour appliquer la configuration.

Si les configurations par instance n'existent pas encore pour les instances données, utilisez la méthode instanceGroupManagers.updatePerInstanceConfigs avec des métadonnées avec état :

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/updatePerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

Si des configurations par instance existent déjà pour les instances données, utilisez la méthode instanceGroupManagers.patchPerInstanceConfigs.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "INSTANCE_NAME",
      "preservedState" : {
        "metadata": {
          "KEY": "VALUE",
          ...
        }
      },
      "fingerprint: "FINGERPRINT"
    },
    ...
  ]
}

Remplacez les éléments suivants :

PROJECT_ID : ID du projet pour la requête.
ZONE : zone où se trouve le MIG (s'applique à un MIG zonal).
- Pour un MIG régional, remplacez zones/ZONE par regions/REGION et spécifiez la région du MIG.
NAME : nom du MIG.
INSTANCE_NAME : nom de la VM pour laquelle configurer des métadonnées avec état.
KEY et VALUE : paires clé/valeur de métadonnées avec état à définir individuellement pour les instances en plus des métadonnées définies dans le modèle d'instance.
- Les valeurs de métadonnées avec état définies pour des clés pré-existantes dans le modèle d'instance remplacent les valeurs du modèle d'instance.
- Les autres entrées de métadonnées du modèle d'instance ne sont pas affectées et restent disponibles.
- Spécifier null comme valeur supprime la clé de la configuration par instance.
FINGERPRINT : (Facultatif) Empreinte de la configuration donnée, si celle-ci existe déjà. Elle est utilisée pour le verrouillage optimiste.

Les méthodes updatePerInstanceConfigs et patchPerInstanceConfigs mettent à jour les configurations par instance spécifiées, mais n'appliquent pas les mises à jour de configuration aux instances de VM associées. Les modifications sont appliquées à une VM lorsque vous la mettez à jour ou recréez l'instance. Pour appliquer les modifications à une VM, vous pouvez appliquer la mise à jour manuellement ou bien utiliser le programme de mise à jour en mode proactif ou opportuniste.

Exemple

Pour basculer la VM node-12 vers la base et la journalisation vers la version de base, corrigez la configuration par instance associée à l'aide de la méthode patchPerInstanceConfigs :

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/patchPerInstanceConfigs

{
  "perInstanceConfigs": [
    {
      "name": "node-12",
      "preservedState" : {
        "metadata": {
          "mode": "standby",
          "logging": null
        }
      }
    }
  ]
}

La méthode effectue les opérations suivantes :

Elle définit la métadonnée mode:standby dans la configuration par instance associée à la VM, node-12, au sein du groupe d'instances géré example-cluster.
Elle supprime la métadonnée logging:elaborate de la configuration par instance, car la valeur fournie est null.

La mise à jour de la configuration n'est pas encore appliquée à l'instance de VM node-12. La mise à jour de la configuration sera appliquée lors de la prochaine recréation ou de la mise à jour de l'instance, ou si vous utilisez la mise à jour automatique proactive.

Pour appliquer la mise à jour de la configuration par instance à l'instance de VM node-12, appelez la méthode instanceGroupManagers.applyUpdatesToInstances de l'instance :

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/applyUpdatesToInstances

{
  "instances": ["/zones/us-east1-c/instances/node-12"],
  "minimalAction": "NONE"
}

La méthode applique la configuration par instance mise à jour à la VM node-12 :

Elle définit la métadonnée mode:standby suivant la configuration par instance.
Définit les métadonnées logging:basic du modèle d'instance, car la valeur de la clé logging n'est plus définie par la configuration par instance.
La VM continue de s'exécuter pendant la mise à jour, car l'option minimalAction est définie sur NONE, ce qui permet au MIG d'utiliser l'action la moins perturbatrice requise pour la mise à jour. La mise à jour des métadonnées d'une instance nécessite l'action REFRESH, qui ne perturbe pas l'exécution d'une instance.

Commentaires

Nous souhaitons en savoir plus sur vos cas d'utilisation, les défis que vous rencontrez ou vos impressions sur les MIG avec état. Nous vous invitons à nous faire part de vos commentaires à l'adresse suivante : mig-discuss@google.com.

Étape suivante

En savoir plus sur le stockage et la récupération des métadonnées d'instance.
Configurez des disques persistants avec état pour les VM d'un MIG.
Découvrez comment appliquer, afficher et supprimer une configuration avec état.
Apprenez-en plus sur les MIG et l'utilisation d'instances gérées.