Gestire gli eventi di manutenzione con le TPU in modalità Tutte le capacità

Tutti gli host TPU vengono sottoposti a manutenzione regolare. In modalità TPU All Capacity, puoi pianificare i prossimi eventi di manutenzione e avviare le operazioni di manutenzione quando vuoi su tutta la tua capacità. Puoi aggiornare la capacità utilizzata e non utilizzata contemporaneamente o separatamente. Puoi anche eseguire la manutenzione a livello di VM, blocco secondario, blocco o prenotazione. Questo controllo di manutenzione granulare ti consente di creare una sequenza di manutenzione ottimale e pianificare le operazioni di manutenzione per ridurre al minimo l'impatto sull'attività.

La modalità TPU All Capacity supporta solo la "manutenzione raggruppata", il che significa che le operazioni di manutenzione per tutte le istanze VM all'interno di una prenotazione vengono pianificate contemporaneamente. Tutte le VM TPU in una prenotazione hanno lo stesso periodo di manutenzione. Tuttavia, le operazioni di manutenzione possono essere eseguite separatamente a livello di host, blocco secondario, blocco o prenotazione. Le notifiche di manutenzione vengono inviate circa 90 giorni prima. La manutenzione non verrà eseguita più di una volta ogni 90 giorni.

Se utilizzi TPU Cluster Director su GKE e utilizzi node pool di sezioni TPU multi-host, ti consigliamo di eliminare il node pool GKE prima di avviare manualmente la manutenzione in attesa per qualsiasi host in quel node pool. Una volta eseguita la manutenzione per tutti gli host nel pool di nodi originale, puoi ricreare il pool di nodi.

Di seguito è riportato un esempio di cronologia per un evento di manutenzione dell'host TPU:

  1. La manutenzione è pianificata. Ti viene inviata una notifica che indica che l'host verrà aggiornato entro 90 giorni.
  2. Puoi scegliere di aggiornare manualmente l'host entro 90 giorni.
  3. Dopo 90 giorni, l'operazione di manutenzione viene eseguita senza eccezioni.
  4. Se viene pianificato un altro evento di manutenzione prima dell'esecuzione del precedente, la seconda operazione è pianificata per l'esecuzione dopo 180 giorni, 90 giorni dopo la pianificazione dell'evento di manutenzione iniziale.

Configurare gli avvisi di notifica di manutenzione per la capacità fisica

Compute Engine ti invia eventi Cloud Logging per la manutenzione pianificata, avviata o completata. Questi eventi di manutenzione rimangono nei log, in modo da poter creare query di log per ottenere una visualizzazione storica della manutenzione della tua capacità. Puoi anche ricevere notifiche sugli eventi di manutenzione futuri per una prenotazione, blocco o sottoblocco creando policy di avviso basate sui log.

Per creare un avviso per gli eventi di manutenzione della capacità fisica:

  1. Nella console Google Cloud , vai a Esplora log.
  2. Assicurati che l'opzione Mostra query sia attiva.
  3. Nel riquadro della query, crea una query nel formato elencato nelle sezioni seguenti. Sostituisci il segnaposto del parametro corrispondente e esegui la query.
  4. Dopo aver verificato che i risultati restituiti corrispondano a ciò che ti interessa, puoi creare avvisi selezionando Crea avviso log dal menu a discesa Azioni nella barra degli strumenti Risultati query e fornendo le informazioni richieste.

Query per la manutenzione prevista

Di seguito è riportato un esempio di query per interrogare la manutenzione imminente:

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

Sostituisci CAPACITY_COMPONENT e RESOURCE_NAME con i seguenti valori:

Ricevi una notifica di manutenzione imminente per CAPACITY_COMPONENT RESOURCE_NAME
Tutte le prenotazioni reservations Ometti RESOURCE_NAME
Una prenotazione specifica reservations YOUR_RESERVATION_NAME
Blocchi in tutte le prenotazioni reservations.blocks Ometti RESOURCE_NAME
Un blocco specifico reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
Blocchi secondari in tutte le prenotazioni reservations.blocks.subblocks Ometti RESOURCE_NAME
Un blocco secondario specifico reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

Query per l'apertura del periodo di manutenzione

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

Sostituisci CAPACITY_COMPONENT con uno dei seguenti valori:

Ricevere una notifica per l'apertura di un periodo di manutenzione per CAPACITY_COMPONENT
Blocchi in una prenotazione reservations.blocks
Blocchi secondari in una prenotazione reservations.blocks.subblocks

Query per la manutenzione completata

Di seguito è riportato un esempio di query per eseguire query sulla manutenzione completata:

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

Sostituisci CAPACITY_COMPONENT e RESOURCE_NAME con i seguenti valori:

Ricevi una notifica per la manutenzione completata per CAPACITY_COMPONENT RESOURCE_NAME
Tutte le prenotazioni reservations Ometti RESOURCE_NAME
Una prenotazione specifica reservations YOUR_RESERVATION_NAME
Blocchi in tutte le prenotazioni reservations.blocks Ometti RESOURCE_NAME
Un blocco specifico reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
Blocchi secondari in tutte le prenotazioni reservations.blocks.subblocks Ometti RESOURCE_NAME
Un blocco secondario specifico reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

Visualizzare lo stato di manutenzione della capacità fisica

Puoi scoprire lo stato di manutenzione della tua capacità tramite Cloud Logging, API e CLI. Le informazioni sullo stato della manutenzione sono fornite a quattro livelli: prenotazione, blocco, sottoblocco e host.

Cloud Logging

Il seguente JSON di esempio è stato generato in risposta a questa query di esempio:

{
"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

L'output è simile al seguente:

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'
…

I seguenti valori dell'output descrivono le informazioni sulla manutenzione:

  • reservationMaintenance.instanceMaintenanceOngoingCount: il numero di host utilizzati in fase di aggiornamento
  • reservationMaintenance.instanceMaintenancePendingCount: il numero di host utilizzati in attesa di manutenzione
  • reservationMaintenance.maintenanceOngoingCount: il numero di host inutilizzati in fase di aggiornamento
  • reservationMaintenance.maintenancePendingCount: il numero di host inutilizzati in attesa di manutenzione
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceReasons: il tipo di manutenzione
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceStatus: lo stato dell'operazione di manutenzione
  • reservationMaintenance.upcomingGroupMaintenance.type: il tipo di manutenzione (SCHEDULED per la manutenzione pianificata o UNSCHEDULED per la manutenzione non pianificata o di emergenza)
  • reservationMaintenance.upcomingGroupMaintenance.windowEndTime: la fine pianificata della finestra temporale per l'operazione di manutenzione
  • reservationMaintenance.upcomingGroupMaintenance.windowStartTime: l'inizio pianificato dell'intervallo di tempo per l'operazione di manutenzione

Configurare gli avvisi di notifica di manutenzione per le VM TPU

Puoi creare avvisi per gli eventi di manutenzione sulle tue VM TPU:

  1. Nella console Google Cloud , vai a Esplora log.
  2. Imposta il pulsante di attivazione/disattivazione Mostra query su "Attivo".
  3. Nel riquadro della query, crea una query nel formato elencato nelle sezioni seguenti.
  4. Una volta verificato che i risultati restituiti corrispondano a ciò che vuoi, puoi creare un avviso facendo clic sul menu a discesa Azioni, selezionando Crea avviso log e completando le informazioni nel riquadro Crea criterio di avviso basato sui log.

Esegui query per quando è pianificata la manutenzione di un'istanza VM

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

Esegui query per sapere quando è stato aperto il periodo di manutenzione per un'istanza VM

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

Query per la manutenzione avviata per le istanze VM

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

Esegui una query per sapere quando è stata completata la manutenzione di un'istanza VM

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

Visualizza lo stato di manutenzione di una VM Cloud TPU

Puoi recuperare lo stato di manutenzione di una VM Cloud TPU con l'API Compute Engine Instance o con un comando curl dal sistema operativo guest.

Descrivi un'istanza

gcloud 

gcloud compute instances describe INSTANCE --zone ZONE

Questo comando restituisce un output simile al seguente:

…
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"

Questo comando restituisce un output simile al seguente:

{
"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"
}

Puoi trovare le notifiche di manutenzione anche in Cloud Logging.

Di seguito è riportato un esempio di messaggio di log di una manutenzione pianificata in attesa. Per una query di esempio, vedi Visualizzare lo stato di manutenzione della capacità fisica.

{
  "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'esempio seguente è un messaggio di log di una manutenzione non pianificata in corso. Per una query di esempio, consulta Query per quando è aperto un periodo di manutenzione.

{
  "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
  },
}

Il seguente esempio è un messaggio di log per la manutenzione completata. Per un esempio di query, consulta Query per quando la manutenzione è stata completata per un'istanza VM.

{
  "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
  },
}

Avviare manualmente la manutenzione in attesa per la capacità fisica

Una volta pianificato un evento di manutenzione (maintenanceStatus è impostato su PENDING), puoi avviare manualmente la manutenzione per le prenotazioni, i blocchi o i sottoblocchi che hanno la proprietà canReschedule impostata su True. Quando avvii manualmente un evento di manutenzione in attesa, ciò che accade dipende dallo stato di manutenzione della prenotazione, dei blocchi o dei blocchi secondari. La tabella seguente descrive cosa succede per ciascuna di queste situazioni:

Stato di manutenzione Descrizione Cosa vedi
Pianificato Compute Engine ha pianificato la manutenzione per la prenotazione. Puoi avviare manualmente la manutenzione prima dell'orario pianificato. In Google Cloud CLI o nell'API REST, il campo maintenanceStatus è impostato su PENDING.
In corso La manutenzione è in corso. Non puoi riprogrammarlo. In Google Cloud CLI o nell'API REST, il campo maintenanceStatus è impostato su ONGOING.
Completa La manutenzione è terminata. Compute Engine ha rimosso tutte le notifiche di manutenzione dalla VM. In Google Cloud CLI o nell'API REST, il campo maintenanceStatus non esiste.

Avviare manualmente la manutenzione dell'intera prenotazione

Il seguente comando avvia la manutenzione di una prenotazione. Utilizza il parametro --scope per specificare uno dei seguenti valori che indicano l'ambito dell'operazione di manutenzione:

  • Tutti gli host: --scope=all
  • Host con VM in esecuzione: --scope=running
  • VM inutilizzate, arrestate o sospese: --scope=unused

Per avviare la manutenzione di tutti i blocchi di una prenotazione, esegui questo comando:

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

Per controllare l'avanzamento di un evento di manutenzione, esegui questo comando:

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

L'output è simile al seguente:

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.

Avviare manualmente la manutenzione di un blocco

Il seguente comando avvia la manutenzione di un blocco. Utilizza il parametro --scope per specificare uno dei seguenti valori che indicano l'ambito dell'operazione di manutenzione:

  • Tutti gli host: --scope=all
  • Host con VM in esecuzione: --scope=running
  • VM inutilizzate, arrestate o sospese: --scope=unused

Il seguente comando mostra come avviare la manutenzione sugli host in esecuzione:

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

Il seguente comando mostra come controllare l'avanzamento della manutenzione per un blocco:

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

L'output è simile al seguente:

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

Avviare manualmente la manutenzione di un blocco secondario

Quando avvii la manutenzione di un blocco secondario, non specificare il parametro --scope perché un blocco secondario è l'ambito di manutenzione più piccolo.

Il seguente comando avvia la manutenzione di tutti gli host di un blocco:

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

Il seguente comando controlla l'avanzamento della manutenzione:

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

L'output è simile al seguente:

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

Avvia manualmente la manutenzione in attesa per una VM TPU

Se un host esegue più di una VM, l'avvio della manutenzione su una VM attiva la manutenzione per tutte le VM sull'host.

L'esempio seguente mostra come attivare manualmente la manutenzione per un host Trillium con due VM, vm-1 e vm-2:

gcloud compute instances perform-maintenance vm-1

L'avvio della manutenzione di vm-1 attiverà la manutenzione di vm-2.