Mettre à jour les propriétés d'une instance

Vous pouvez utiliser une seule requête de la CLI Google Cloud ou de l'API Compute Engine pour mettre à jour plusieurs propriétés d'instance et éventuellement redémarrer l'instance, si nécessaire. La méthode de mise à jour gère la logique pour valider les propriétés d'instance mises à jour et garantir que les ressources nécessaires sont disponibles pour terminer la mise à jour correctement. Si la demande comprend des propriétés non valides ou si les ressources demandées ne sont pas disponibles, la requête renvoie une erreur et n'apporte aucune modification à votre instance. Cela protège l'instance des mises à jour partielles, et lui évite d'être arrêtée et de ne pas pouvoir accéder aux ressources pour redémarrer.

Avant de commencer

  • 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
    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.

      Installez Google Cloud CLI, puis initialisez-la en exécutant la commande suivante : 

      gcloud init

Restrictions

  • Les requêtes de mise à jour d'instance via gcloud CLI ou l'API Compute Engine ne prennent pas en charge la sémantique PATCH. La ressource d'instance dans la requête de mise à jour doit inclure toutes les propriétés de l'instance. Les propriétés manquantes dans la configuration de l'instance dans votre requête de mise à jour sont considérées comme supprimées de l'instance.
  • Vous ne pouvez mettre à jour qu'une liste spécifique de propriétés.
  • Il n'est pas possible de modifier des instances depuis et vers une location unique.
  • Vous pouvez modifier une instance d'une réservation à une autre, mais vous ne pouvez pas associer une instance à une réservation, ou l'en dissocier, à l'aide du processus de mise à jour.
  • Si l'instance est associée à un SSD local, vous ne pouvez pas mettre à jour les propriétés qui nécessitent le redémarrage d'une instance. Vous devez supprimer l'instance, puis la recréer. Assurez-vous de migrer vos données critiques du SSD local vers un disque persistant ou vers une autre VM avant de supprimer la VM.
  • Si une instance utilise des ressources disponibles uniquement dans l'API Compute Engine version bêta, vous devez utiliser la bonne version de la méthode instances.update pour mettre à jour ces propriétés. Par exemple, si vous créez une instance à l'aide de l'API Compute Engine version bêta et configurez l'instance avec une ressource que seule l'API version bêta reconnaît, vous devez également utiliser la version bêta de la méthode instances.update pour mettre à jour ces ressources. La version v1 de la méthode instances.update ne reconnaît pas les ressources bêta utilisées par votre instance. Par conséquent, elle supprime ces ressources bêta de la configuration de l'instance lors du processus de mise à jour. Cela s'applique également aux ressources de l'API version alpha.

Autorisations

Vous devez disposer de l'autorisation compute.instances.update pour pouvoir mettre à jour des instances. Cette autorisation est incluse dans plusieurs rôles de gestion de l'authentification et des accès (IAM) existants. Vous devez également être autorisé à utiliser les ressources que vous souhaitez modifier sur l'instance. Par exemple, pour ajouter un disque à une instance, vous devez disposer des autorisations suivantes :

  • L'autorisation compute.instances.update sur l'instance que vous souhaitez mettre à jour.
  • L'autorisation compute.disks.use pour un disque existant ou compute.disks.create pour un projet pour lequel vous souhaitez créer un disque.

Bonnes pratiques

Pour vous assurer que l'interface de mise à jour de l'instance fonctionne au mieux, suivez les bonnes pratiques suivantes :

  • Si possible, utilisez systématiquement la même version de l'API Compute Engine pour créer, définir et mettre à jour des instances. Cela vous garantit de pouvoir mettre à jour et modifier toutes les ressources d'instance si elles ne sont disponibles que dans une seule version de l'API.
  • Bien que vous puissiez utiliser la méthode instances.update pour mettre à jour des instances dans un groupe d'instances géré (MIG), dans la plupart des cas, il est préférable de modifier le modèle d'instance du groupe, puis de déployer cette mise à jour dans le MIG.

Propriétés pouvant être mises à jour

Vous ne pouvez modifier qu'un ensemble spécifique de propriétés d'instance via la méthode de mise à jour. Les mises à jour de certaines propriétés nécessitent le redémarrage de l'instance. Pour éviter les redémarrages accidentels sur vos instances, votre requête doit définir le type d'action qui est autorisé sur vos instances. Votre requête peut spécifier l'une des actions suivantes :

  • NO_EFFECT : la requête de mise à jour vérifie si la requête est valide et si les ressources sont disponibles, mais n'exécute pas la mise à jour. Utilisez cette option pour tester des commandes sans lancer de véritables mises à jour.
  • REFRESH : la requête de mise à jour ne s'exécute que si les propriétés modifiées de l'instance ne nécessitent pas de la redémarrer. Une erreur INFEASIBLE est renvoyée si la requête est valide, mais nécessite un redémarrage.
  • RESTART : si la mise à jour nécessite le redémarrage de l'instance, le système la redémarre.

Les propriétés qui nécessitent un redémarrage (RESTART) pour la mise à jour :

  • reservationAffinity
  • disks - Disques de démarrage
    • disks.deviceName - Tous les disques
  • displayDevice
  • enableNestedVirtualization
  • guestAccelerators
  • machineType
  • minCpuPlatform
  • networkPerformanceConfig
  • resourcePolicies
  • scheduling
  • serviceAccounts
  • shieldedInstanceConfig
  • threadsPerCore
  • visibleCoreCount

Propriétés qui nécessitent uniquement une actualisation (REFRESH) pour la mise à jour :

  • canIpForward
  • deletionProtection
  • description
  • disks - Propriétés de disque non amorçable, à l'exception de deviceName
  • labels
  • metadata
  • nodeAffinities
  • tags

Mettre à jour les propriétés d'une instance

Mettez à jour vos instances en procédant comme suit :

  1. Exportez les propriétés de configuration de l'instance.
  2. Modifiez les propriétés de configuration de l'instance.
  3. Exécutez une requête de test en spécifiant NO_EFFECT comme action la plus perturbatrice. La réponse indique les champs non valides dans la configuration de l'instance et l'action requise pour appliquer les modifications.
  4. Si la configuration est acceptable, demandez une mise à jour d'instance et spécifiez l'action la plus perturbatrice acceptable pour la mise à jour de votre instance.

Le système ne lance le processus de mise à jour que si votre requête répond aux exigences suivantes :

  • La propriété fingerprint de l'instance de votre requête doit correspondre à la propriété fingerprint de l'instance que vous mettez à jour. Cela empêche les demandes de mise à jour simultanées sur une même instance de s'écraser.
  • Les propriétés de votre requête de mise à jour doivent être valides.
  • Les ressources que vous demandez doivent être disponibles.
  • Si les propriétés de votre requête nécessitent un redémarrage de l'instance, la requête doit spécifier RESTART comme action autorisée.

Si les exigences sont remplies, le système démarre le processus de mise à jour de l'instance. Sinon, le système n'apporte aucune modification à votre instance existante ou à sa configuration.

Vous pouvez lancer des mises à jour à l'aide de gcloud CLI ou de l'API Compute Engine.

gcloud

  1. Utilisez la commande instances export pour exporter les propriétés existantes de l'instance :

    gcloud compute instances export INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --destination=FILE_PATH

    Remplacez l'élément suivant :

    • INSTANCE_NAME : nom de l'instance à exporter.
    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance.
    • FILE_PATH : emplacement où enregistrer le fichier de configuration de l'instance sur votre poste de travail local.

  2. Utilisez un éditeur de texte pour modifier une ou plusieurs propriétés du fichier de configuration d'instance exporté. Pour savoir quelles propriétés vous pouvez mettre à jour, consultez la liste des propriétés pouvant être mises à jour. Par exemple, pour changer le type de machine de l'instance, modifiez la propriété machineType.

    ⋮
machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE
⋮

    Remplacez l'élément suivant :

    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance.
    • MACHINE_TYPE : le type de machine de l'instance. Par exemple, n1-standard-2.

  3. Utilisez la commande instances update-from-filepour exécuter une mise à jour de test de l'instance cible. Spécifiez l'option --most-disruptive-allowed-action=NO_EFFECT. La réponse identifie les propriétés mal configurées et indique si une action RESTART ou REFRESH est nécessaire pour appliquer la mise à jour.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action NO_EFFECT

    Remplacez l'élément suivant :

    • INSTANCE_NAME : nom de l'instance à exporter.
    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance.
    • FILE_PATH : chemin d'accès au fichier de configuration d'instance modifié sur votre poste de travail local.

  4. Exécutez la commande instances update-from-file pour mettre à jour l'instance cible. Si vous mettez à jour une propriété qui nécessite le redémarrage de l'instance, incluez l'option --most-disruptive-allowed-action=RESTART. Si les propriétés ne nécessitent pas de redémarrage, spécifiez l'option --most-disruptive-allowed-action=REFRESH. Pour savoir quelles propriétés nécessitent un redémarrage, consultez la liste des propriétés pouvant être mises à jour.

    gcloud compute instances update-from-file INSTANCE_NAME \
    --project PROJECT_ID \
    --zone ZONE \
    --source=FILE_PATH \
    --most-disruptive-allowed-action ALLOWED_ACTION

    Remplacez l'élément suivant :

    • INSTANCE_NAME : nom de l'instance à exporter.
    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance.
    • FILE_PATH : chemin d'accès au fichier de configuration d'instance modifié sur votre poste de travail local.
    • ALLOWED_ACTION : niveau de perturbation de la mise à jour. Spécifiez RESTART pour permettre un redémarrage complet de l'instance. Spécifiez REFRESH pour mettre à jour l'instance uniquement si les propriétés modifiées ne nécessitent pas de redémarrer l'instance.

Si la requête de mise à jour est valide et que les ressources requises sont disponibles, le processus de mise à jour de l'instance commence. Vous pouvez surveiller l'état de cette opération en affichant les journaux d'audit. Si la mise à jour nécessite un redémarrage et que votre commande autorise l'action RESTART, l'instance redémarre pour appliquer les modifications.

REST

  1. Utilisez la méthode instances.get de l'API Compute Engine pour exporter les propriétés de l'instance :

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

    Remplacez les éléments suivants :

    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance
    • INSTANCE_NAME : nom de l'instance à exporter.

    Cette requête renvoie une définition des ressources d'instance.

  2. Dans la réponse, modifiez les propriétés de la ressource d'instance. Pour savoir quelles propriétés peuvent être mises à jour, consultez la liste des propriétés pouvant être mises à jour. Par exemple, pour changer le type de machine de l'instance, modifiez la propriété machineType. Vous pouvez modifier plusieurs propriétés.

    {
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE",
  ⋮
}

    Remplacez les éléments suivants :

    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance.
    • MACHINE_TYPE : type de machine de l'instance. Par exemple, n1-standard-2.

  3. Utilisez la méthode instances.update dans l'API Compute Engine et spécifiez most_disruptive_allowed_action=NO_EFFECT pour exécuter une mise à jour de test de l'instance cible. La réponse identifie les propriétés mal configurées et indique si une action RESTART ou REFRESH est nécessaire pour appliquer la mise à jour.

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=NO_EFFECT

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    Remplacez l'élément suivant :

    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance.
    • INSTANCE_NAME : nom de l'instance à exporter.

  4. Utilisez la méthode instances.update dans l'API Compute Engine pour mettre à jour l'instance cible. Si vous mettez à jour une propriété nécessitant un redémarrage de l'instance, incluez le paramètre de requête ?most_disruptive_allowed_action=RESTART pour indiquer que l'instance peut être redémarrée pendant la mise à jour. Si les propriétés ne nécessitent pas de redémarrage, spécifiez le paramètre de requête ?most_disruptive_allowed_action=REFRESH. Pour savoir quelles propriétés nécessitent un redémarrage, consultez la liste des propriétés pouvant être mises à jour. Incluez le corps complet de la ressource d'instance que vous avez modifiée. Dans l'exemple suivant, le corps remplace le type de machine par n1-standard-2 :

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=ALLOWED_ACTION

{
  ⋮
  "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
  ⋮
}

    Remplacez l'élément suivant :

    • PROJECT_ID : ID du projet pour cette requête.
    • ZONE : zone de l'instance.
    • INSTANCE_NAME : nom de l'instance à exporter.
    • ALLOWED_ACTION : niveau de perturbation de la mise à jour. Spécifiez RESTART pour permettre un redémarrage complet de l'instance. Spécifiez REFRESH pour mettre à jour l'instance uniquement si les propriétés modifiées ne nécessitent pas de redémarrer l'instance.

Si la requête de mise à jour est valide et que les ressources requises sont disponibles, le processus de mise à jour de l'instance commence. Vous pouvez surveiller l'état de cette opération en affichant les journaux d'audit. Si la mise à jour nécessite un redémarrage et que votre commande autorise l'action RESTART, l'instance redémarre pour appliquer les modifications.

Étape suivante