Gérer les événements de maintenance avec les TPU en mode "Toute capacité"

Tous les hôtes TPU font l'objet d'une maintenance régulière. En mode "Toute la capacité TPU", vous pouvez planifier les événements de maintenance à venir et lancer les opérations de maintenance quand vous le souhaitez sur l'ensemble de votre capacité. Vous pouvez modifier votre capacité utilisée et inutilisée, simultanément ou séparément. Vous pouvez également effectuer la maintenance au niveau d'une VM, d'un sous-bloc, d'un bloc ou d'une réservation. Ce contrôle précis de la maintenance vous permet de créer une séquence de maintenance optimale et de planifier les opérations de maintenance afin de minimiser l'impact sur votre activité.

Le mode "Toute capacité TPU" n'est compatible qu'avec la "maintenance groupée", ce qui signifie que les opérations de maintenance pour toutes les instances de VM d'une réservation sont planifiées en même temps. Toutes les VM TPU d'une réservation ont le même intervalle de maintenance. Toutefois, les opérations de maintenance peuvent être effectuées séparément au niveau de l'hôte, du sous-bloc, du bloc ou de la réservation. Les notifications de maintenance sont envoyées environ 90 jours à l'avance. La maintenance ne sera pas effectuée plus d'une fois tous les 90 jours.

Si vous utilisez TPU Cluster Director sur GKE et des pools de nœuds de tranche TPU multi-hôte, nous vous recommandons de supprimer le pool de nœuds GKE avant de démarrer manuellement la maintenance en attente pour les hôtes de ce pool de nœuds. Une fois la maintenance effectuée pour tous les hôtes du pool de nœuds d'origine, vous pouvez recréer le pool de nœuds.

Voici un exemple de calendrier pour un événement de maintenance d'hôte TPU :

  1. Une opération de maintenance est prévue. Vous recevez une notification vous informant que l'hôte sera mis à jour dans les 90 jours.
  2. Vous pouvez choisir de mettre à jour manuellement l'hôte sous 90 jours.
  3. Au bout de 90 jours, l'opération de maintenance est exécutée sans exception.
  4. Si un autre événement de maintenance est planifié avant l'exécution du précédent, la deuxième opération est planifiée pour être exécutée après 180 jours, soit 90 jours après la date prévue de l'événement de maintenance initial.

Configurer des alertes de notification de maintenance pour la capacité physique

Compute Engine vous envoie des événements Cloud Logging pour la maintenance planifiée, commencée ou terminée. Ces événements de maintenance restent dans vos journaux. Vous pouvez ainsi créer des requêtes de journaux pour obtenir un historique de la maintenance de votre capacité. Vous pouvez également recevoir des notifications concernant les futurs événements de maintenance pour une réservation, un bloc ou un sous-bloc en créant des règles d'alerte basées sur les journaux.

Pour créer une alerte pour les événements de maintenance sur votre capacité physique :

  1. Dans la console Google Cloud , accédez à l'explorateur de journaux.
  2. Assurez-vous que l'option Afficher la requête est activée.
  3. Dans le volet "Requête", créez une requête au format indiqué dans les sections suivantes. Remplacez l'espace réservé du paramètre correspondant et exécutez la requête.
  4. Une fois que vous avez vérifié que les résultats renvoyés correspondent à ce que vous souhaitez, vous pouvez créer des alertes en sélectionnant Créer une alerte de journal dans le menu déroulant Actions de la barre d'outils des résultats de requête, puis en fournissant les informations demandées.

Demander des informations sur les opérations de maintenance à venir

Voici un exemple de requête permettant d'interroger les événements de maintenance à venir :

protoPayload.methodName="compute.CAPACITY_COMPONENT.upcomingGroupMaintenance" severity>=DEFAULT
protoPayload.resourceName="projects/shared-reservation-project/reservations/RESOURCE_NAME"
protoPayload.status.message =~ "scheduled"

Remplacez CAPACITY_COMPONENT et RESOURCE_NAME par les valeurs suivantes :

Recevoir une notification de maintenance à venir pour CAPACITY_COMPONENT RESOURCE_NAME
Toutes les réservations reservations Omettez RESOURCE_NAME.
Une réservation spécifique reservations YOUR_RESERVATION_NAME
Blocs pour toutes les réservations reservations.blocks Omettez RESOURCE_NAME.
Un bloc spécifique reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
Sous-blocs pour toutes les réservations reservations.blocks.subblocks Omettez RESOURCE_NAME.
Un sous-bloc spécifique reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

Demande d'ouverture d'un intervalle de maintenance

protoPayload.methodName="compute.reservations.CAPACITY_COMPONENT.startGroupMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "started"

Remplacez CAPACITY_COMPONENT par l'une des valeurs suivantes :

Recevoir une notification pour l'ouverture d'un intervalle de maintenance pour CAPACITY_COMPONENT
Blocs dans une réservation reservations.blocks
Sous-blocs dans une réservation reservations.blocks.subblocks

Demander l'état d'une maintenance terminée

Voici un exemple de requête permettant d'interroger les maintenances terminées :

protoPayload.methodName="compute.reservations.CAPACITY_COMPONENT.completedGroupMaintenance" severity>=DEFAULT
protoPayload.resourceName="projects/YOUR_RESERVATION_PROJECT/reservations/RESOURCE"
protoPayload.status.message =~ "completed"

Remplacez CAPACITY_COMPONENT et RESOURCE_NAME par les valeurs suivantes :

Recevoir une notification pour la maintenance terminée pour CAPACITY_COMPONENT RESOURCE_NAME
Toutes les réservations reservations Omettre RESOURCE_NAME
Une réservation spécifique reservations YOUR_RESERVATION_NAME
Blocs pour toutes les réservations reservations.blocks Omettre RESOURCE_NAME
Un bloc spécifique reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
Sous-blocs pour toutes les réservations reservations.blocks.subblocks Omettre RESOURCE_NAME
Un sous-bloc spécifique reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

Afficher l'état de maintenance de la capacité physique

Vous pouvez connaître l'état de maintenance de votre capacité via Cloud Logging, les API et la CLI. Les informations sur l'état de maintenance sont fournies à quatre niveaux : réservation, bloc, sous-bloc et hôte.

Cloud Logging

L'exemple JSON suivant a été généré en réponse à cet exemple de requête :

{
"protoPayload": {
  "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
  "status": {
    "message": "Maintenance is scheduled for this block in reservation
    YOUR_RESERVATION. Review the maintenance schedule
    by describing the reservation and block via gcloud CLI"
  },
  "metadata": {
    "type":SCHEDULED
    "canReschedule":True
    "windowGroupStartTime": '2025-09-12T13:00:00.000-07:00',
    "windowGroupEndTime": '2025-09-12T17:00:00.000-07:00',
    "maintenanceGroupStatus":PENDING,
    "maintenancePendingCount":128 # Used and Unused Machines,
    "instanceMaintenancePendingCount": 64 # VMs Only
  },
"methodName": "compute.reservations.block.upcomingGroupMaintenance",
…
},
}

gcloud 

gcloud compute reservations blocks describe YOUR_RESERVATION \
--block-name=YOUR_BLOCK \
--project=YOUR_PROJECT \
--zone=YOUR_ZONE

Le résultat ressemble à ce qui suit :

count: 128 # Host count
creationTimestamp: '2025-08-19T18:23:32.825-07:00'
id: '6404259976725386932'
inUseCount: 64 # In use host count
kind: compute#reservationBlock
name: exr1-block-0002
…
reservationMaintenance:
instanceMaintenanceOngoingCount: 0
instanceMaintenancePendingCount: 64 # VMs Only
maintenanceOngoingCount: 0
maintenancePendingCount: 128 # Used and Unused Hosts
schedulingType: GROUPED
subblockInfraMaintenanceOngoingCount: 0
subblockInfraMaintenancePendingCount: 0
upcomingGroupMaintenance:
  canReschedule: true
  maintenanceReasons:
  - PLANNED_UPDATE
  maintenanceStatus: PENDING
  type: SCHEDULED
  windowEndTime: '2025-09-12T17:00:00.000-07:00'
  windowStartTime: '2025-09-12T13:00:00.000-07:00'
…

Les valeurs suivantes du résultat décrivent les informations de maintenance :

  • reservationMaintenance.instanceMaintenanceOngoingCount : nombre d'hôtes utilisés en cours de mise à jour
  • reservationMaintenance.instanceMaintenancePendingCount : nombre d'hôtes utilisés en attente de maintenance
  • reservationMaintenance.maintenanceOngoingCount : nombre d'hôtes inutilisés en cours de mise à jour
  • reservationMaintenance.maintenancePendingCount : nombre d'hôtes inutilisés en attente de maintenance
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceReasons : type de maintenance
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceStatus : état de l'opération de maintenance
  • reservationMaintenance.upcomingGroupMaintenance.type : type de maintenance (SCHEDULED pour la maintenance planifiée ou UNSCHEDULED pour la maintenance non planifiée ou d'urgence)
  • reservationMaintenance.upcomingGroupMaintenance.windowEndTime : fin prévue de la période de l'opération de maintenance
  • reservationMaintenance.upcomingGroupMaintenance.windowStartTime : début prévu de la période de l'opération de maintenance

Configurer des alertes de notification de maintenance pour les VM TPU

Vous pouvez créer des alertes pour les événements de maintenance sur vos VM TPU :

  1. Dans la console Google Cloud , accédez à l'explorateur de journaux.
  2. Activez le bouton Afficher la requête.
  3. Dans le volet "Requête", créez une requête au format indiqué dans les sections suivantes.
  4. Une fois que vous avez vérifié que les résultats renvoyés correspondent à ce que vous souhaitez, vous pouvez créer une alerte en cliquant sur le menu déroulant Actions, en sélectionnant Créer une alerte de journal et en saisissant les informations dans le volet Créer une règle d'alerte basée sur les journaux.

Requête permettant de savoir quand une opération de maintenance est prévue pour une instance de VM

protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "scheduled"

Requête pour savoir quand l'intervalle de maintenance s'est ouvert pour une instance de VM

protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "ongoing"

Requête de maintenance démarrée pour les instances de VM

protoPayload.methodName="compute.instances.blocks.terminateOnHostMaintenance" severity>=DEFAULT

Requête pour savoir quand la maintenance d'une instance de VM est terminée

protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULT
protoPayload.status.message =~ "completed"

Afficher l'état de maintenance d'une VM Cloud TPU

Vous pouvez récupérer l'état de maintenance d'une VM Cloud TPU avec l'API d'instance Compute Engine ou avec une commande curl depuis le système d'exploitation invité.

Décrire une instance

gcloud 

gcloud compute instances describe INSTANCE --zone ZONE

La commande renvoie un résultat semblable à celui-ci :

…
upcomingMaintenance:{
"type":"SCHEDULED"
"canReschedule":True
"windowStartTime": '2025-09-12T13:00:00.000-07:00'
"windowEndTime": '2025-09-12T17:00:00.000-07:00'
"latestWindowStartTime": '2025-09-12T13:00:00.000-07:00'
"maintenanceStatus":"PENDING"
...

curl

curl http://metadata.google.internal/computeMetadata/v1/instance/upcoming-maintenance?alt=json -H "Metadata-Flavor: Google"

La commande renvoie un résultat semblable à celui-ci :

{
"maintenanceType":"SCHEDULED"
"canReschedule":True
"windowStartTime": '2025-09-12T13:00:00.000-07:00'
"windowEndTime": '2025-09-12T17:00:00.000-07:00'
"latestWindowStartTime": '2025-09-12T13:00:00.000-07:00'
"maintenanceStatus":"PENDING"
}

Vous pouvez également trouver les notifications de maintenance dans Cloud Logging.

Voici un exemple de message de journal pour une maintenance planifiée en attente. Pour obtenir un exemple de requête, consultez Afficher l'état de maintenance de la capacité physique.

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "status": {
      "message": "Maintenance is scheduled for this instance. Review the maintenance schedule by describing the VM with gcloud CLI or querying the http://metadata.google.internal/computeMetadata/v1/instance/upcoming-maintenance metadata key."
    },
    "metadata": {
      "canReschedule": true
      "latestWindowStartTime": "2024-01-01:00:00:00PST"
      "maintenanceStatus": "PENDING"
      "type": "SCHEDULED"
      "windowEndTime": "2024-01-01:00:02:00PST"
      "windowStartTime": "2024-01-01:00:00:00PST"
    },
},
  "operation": {
    "id": "systemevent-1702539760425-60c736da2db40-701ddf19-b5424b20",
    "producer": "compute.instances.upcomingMaintenance",
    "first": true,
    "last": false
  },
}

L'exemple suivant est un message de journal d'une maintenance non planifiée en cours. Pour obtenir un exemple de requête, consultez Requête pour savoir quand un intervalle de maintenance est ouvert.

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "status": {
      "message": "Maintenance window has started for this instance. Review the maintenance schedule by describing the VM with gcloud CLI or querying the http://metadata.google.internal/computeMetadata/v1/instance/upcoming-maintenance metadata key."
    },
    "metadata": {
      "canReschedule": true
      "latestWindowStartTime": "2024-01-01:00:00:00PST"
      "maintenanceStatus": "ONGING"
      "type": "UNSCHEDULED"
      "windowEndTime": "2024-01-01:00:02:00PST"
      "windowStartTime": "2024-01-01:00:00:00PST"
    },
},
  "operation": {
    "id": "systemevent-1702539760425-60c736da2db40-701ddf19-b5424b20",
    "producer": "compute.instances.upcomingMaintenance",
    "first": true,
    "last": false
  },
}

L'exemple suivant est un message de journal pour une maintenance terminée. Pour obtenir un exemple de requête, consultez Requête pour savoir quand la maintenance d'une instance de VM est terminée.

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "status": {
      "message": "Maintenance window has completed for this instance. All maintenance notifications on the instance have been removed."
    },
  "operation": {
    "id": "systemevent-1702539760425-60c736da2db40-701ddf19-b5424b20",
    "producer": "compute.instances.upcomingMaintenance",
    "first": false,
    "last": true
  },
}

Démarrer manuellement la maintenance en attente pour la capacité physique

Une fois un événement de maintenance planifié (maintenanceStatus défini sur PENDING), vous pouvez démarrer manuellement la maintenance de vos réservations, blocs ou sous-blocs dont la propriété canReschedule est définie sur True. Lorsque vous démarrez manuellement un événement de maintenance en attente, ce qui se passe dépend de l'état de maintenance de votre réservation, de vos blocs ou de vos sous-blocs. Le tableau suivant décrit ce qui se passe pour chacun d'eux :

État de maintenance Description Ce que vous voyez
Programmée Compute Engine a planifié une maintenance pour la réservation. Vous pouvez démarrer manuellement la maintenance avant l'heure prévue. Dans Google Cloud CLI ou l'API REST, le champ maintenanceStatus est défini sur PENDING.
En cours Une opération de maintenance est en cours. Vous ne pouvez pas la reprogrammer. Dans Google Cloud CLI ou l'API REST, le champ maintenanceStatus est défini sur ONGOING.
Terminé La maintenance est terminée. Compute Engine a supprimé toutes les notifications de maintenance de la VM. Dans Google Cloud CLI ou l'API REST, le champ maintenanceStatus n'existe pas.

Démarrer manuellement la maintenance de l'ensemble de la réservation

La commande suivante lance la maintenance d'une réservation. Utilisez le paramètre --scope pour spécifier l'une des valeurs suivantes qui définissent le champ d'application de l'opération de maintenance :

  • Tous les organisateurs : --scope=all
  • Hôtes avec des VM en cours d'exécution : --scope=running
  • VM inutilisées, arrêtées ou suspendues : --scope=unused

Pour lancer la maintenance sur tous les blocs d'une réservation, exécutez la commande suivante :

gcloud compute reservations perform-maintenance YOUR_RESERVATION \
  --zone=YOUR_ZONE \
  --scope=all

Pour vérifier la progression d'un événement de maintenance, exécutez la commande suivante :

gcloud compute reservations describe YOUR_RESERVATION  \
  --project=YOUR_PROJECT \
  --zone=YOUR_ZONE

Le résultat ressemble à ce qui suit :

ResourceStatus
  upcomingGroupMaintenance:
    "type":"SCHEDULED"
    "canReschedule":True
    "maintenanceStatus":"PENDING" → "ONGOING"
    "maintenancePendingCount":512 → 0 # all hosts are moved into an ongoing state.
    "maintenanceOngoingCount":0 → 512 → 256 → 0 # this number first increases to all hosts
                                           # as machines complete, this number reduces.

Démarrer manuellement la maintenance sur un bloc

La commande suivante lance la maintenance d'un bloc. Utilisez le paramètre --scope pour spécifier l'une des valeurs suivantes qui définissent le champ d'application de l'opération de maintenance :

  • Tous les organisateurs : --scope=all
  • Hôtes avec des VM en cours d'exécution : --scope=running
  • VM inutilisées, arrêtées ou suspendues : --scope=unused

La commande suivante montre comment démarrer la maintenance sur les hôtes en cours d'exécution :

gcloud compute reservations perform-maintenance YOUR_RESERVATION
    --scope=RUNNING \
    --project=YOUR_PROJECT \
    --zone=YOUR_ZONE

La commande suivante montre comment vérifier la progression de la maintenance pour un bloc :

gcloud compute reservations blocks describe YOUR_RESERVATION --block-name=YOUR_BLOCK_NAME  \
    --project=YOUR_PROJECT \
    --zone=YOUR_ZONE

Le résultat ressemble à ce qui suit :

ResourceStatus
  upcomingGroupMaintenance:
    "maintenanceType":"SCHEDULED"
…
    "maintenanceGroupStatus":"PENDING" → "ONGOING"
    "maintenancePending":0
 "maintenanceOngoing":70 → 0

Démarrer manuellement la maintenance sur un sous-bloc

Lorsque vous lancez la maintenance d'un sous-bloc, vous ne spécifiez pas le paramètre --scope, car un sous-bloc est la plus petite portée de maintenance.

La commande suivante lance la maintenance sur tous les hôtes d'un bloc :

gcloud compute reservations sub-blocks perform-maintenance YOUR_RESERVATION
    --block-name=YOUR_BLOCK_NAME \
    --sub-block-name=YOUR_SUBBLOCK_NAME \
    --project=YOUR_PROJECT \
    --zone=YOUR_ZONE

La commande suivante vérifie la progression de la maintenance :

gcloud compute reservations sub-blocks describe YOUR_RESERVATION
    --block-name=YOUR_BLOCK_NAME \
    --sub-block-name=YOUR_SUBBLOCK_NAME \
    --project=YOUR_PROJECT \
    --zone=YOUR_ZONE

Le résultat ressemble à ce qui suit :

ResourceStatus
  groupMaintenance:
    "maintenanceType":"SCHEDULED"
    "canReschedule":True
    "maintenanceGroupStatus":"PENDING" → "ONGOING"
    "maintenancePendingCount": 32 → 0 # 32 hosts updated
    "maintenanceOngoingCount":0 → 32 → 0
    "instanceMaintenancePendingCount": 64 → 0
    "instanceMaintenanceOngoingCount": 0 → 64 → 0 # 64 instances updated

Démarrer manuellement la maintenance en attente pour une VM TPU

Si un hôte exécute plusieurs VM, le démarrage de la maintenance sur une VM déclenche la maintenance de toutes les VM de l'hôte.

L'exemple suivant montre comment déclencher manuellement la maintenance d'un hôte Trillium comportant deux VM, vm-1 et vm-2 :

gcloud compute instances perform-maintenance vm-1

Le démarrage de la maintenance de vm-1 déclenchera la maintenance de vm-2.