Faça a gestão de eventos de manutenção com TPUs no modo de capacidade total

Todos os anfitriões de TPUs passam por manutenção regular. No modo de capacidade total da TPU, pode planear eventos de manutenção futuros e iniciar as operações de manutenção quando quiser em toda a sua capacidade. Pode atualizar a capacidade usada e não usada, simultaneamente ou em separado. Também pode realizar a manutenção ao nível de uma VM, de um sub-bloco, de um bloco ou de uma reserva. Este controlo de manutenção detalhado permite-lhe criar uma sequência de manutenção ideal e agendar operações de manutenção para minimizar o impacto na empresa.

O modo de capacidade total da TPU só suporta a "manutenção agrupada", o que significa que as operações de manutenção para todas as instâncias de VM numa reserva são agendadas ao mesmo tempo. Todas as VMs de TPU numa reserva têm a mesma janela de manutenção. No entanto, as operações de manutenção podem ser realizadas separadamente ao nível do anfitrião, do sub-bloco, do bloco ou da reserva. As notificações de manutenção são enviadas com aproximadamente 90 dias de antecedência. A manutenção não é realizada com uma frequência superior a uma vez a cada 90 dias.

Se estiver a usar o TPU Cluster Director no GKE e estiver a usar pools de nós de fatias de TPU com vários anfitriões, recomendamos que elimine o pool de nós do GKE antes de iniciar manualmente a manutenção pendente para quaisquer anfitriões nesse pool de nós. Assim que a manutenção for executada para todos os anfitriões no conjunto de nós original, pode recriar o conjunto de nós.

Segue-se um exemplo de uma cronologia de um evento de manutenção do anfitrião da TPU:

A manutenção está agendada. É-lhe enviada uma notificação a informar que o anfitrião vai ser atualizado no prazo de 90 dias.
Pode optar por atualizar manualmente o anfitrião no prazo de 90 dias.
Após 90 dias, a operação de manutenção é executada sem exceções.
Se for agendado outro evento de manutenção antes da execução do evento anterior, a segunda operação é agendada para execução após 180 dias, 90 dias após a ocorrência agendada do evento de manutenção inicial.

Configure alertas de notificação de manutenção para a capacidade física

O Compute Engine envia-lhe eventos do Cloud Logging para manutenção agendada, iniciada ou concluída. Estes eventos de manutenção permanecem nos seus registos para que possa criar consultas de registos para obter uma vista do histórico da manutenção da sua capacidade. Também pode receber notificações sobre eventos de manutenção futuros para uma reserva, um bloco ou um sub-bloco criando políticas de alerta baseadas em registos.

Para criar um alerta para eventos de manutenção na sua capacidade física:

Na Google Cloud consola, aceda ao Explorador de registos.
Certifique-se de que a opção Mostrar consulta está ativada.
No painel de consultas, crie uma consulta no formato indicado nas secções seguintes. Substitua o marcador de posição do parâmetro correspondente em conformidade e execute a consulta.
Depois de verificar se os resultados devolvidos correspondem ao que pretende, pode criar alertas selecionando Criar alerta de registo no menu pendente Ações na barra de ferramentas de resultados da consulta e fornecer as informações pedidas.

Consultar manutenção futura

Segue-se um exemplo de consulta para consultar a manutenção futura:

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

Substitua CAPACITY_COMPONENT e RESOURCE_NAME pelos seguintes valores:

Receba uma notificação de manutenção futura para	`CAPACITY_COMPONENT`	`RESOURCE_NAME`
Todas as reservas	`reservations`	Omitir `RESOURCE_NAME`
Uma reserva específica	`reservations`	`YOUR_RESERVATION_NAME`
Bloqueios em todas as reservas	`reservations.blocks`	Omitir `RESOURCE_NAME`
Um bloco específico	`reservations.blocks`	`YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID`
Sub-blocos em todas as reservas	`reservations.blocks.subblocks`	Omitir `RESOURCE_NAME`
Um sub-bloco específico	`reservations.blocks.subblocks`	`YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID`

Consulta para a abertura do período de manutenção

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

Substitua CAPACITY_COMPONENT por um dos seguintes valores:

Receba uma notificação quando um período de manutenção for aberto para	`CAPACITY_COMPONENT`
Bloqueios numa reserva	`reservations.blocks`
Sub-blocos numa reserva	`reservations.blocks.subblocks`

Consultar manutenção concluída

Segue-se um exemplo de consulta para consultar a manutenção concluída:

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

Substitua CAPACITY_COMPONENT e RESOURCE_NAME pelos seguintes valores:

Receba notificações sobre a manutenção concluída para	`CAPACITY_COMPONENT`	RESOURCE_NAME
Todas as reservas	`reservations`	Omit RESOURCE_NAME
Uma reserva específica	`reservations`	`YOUR_RESERVATION_NAME`
Bloqueios em todas as reservas	`reservations.blocks`	Omit RESOURCE_NAME
Um bloco específico	`reservations.blocks`	`YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID`
Sub-blocos em todas as reservas	`reservations.blocks.subblocks`	Omit RESOURCE_NAME
Um sub-bloco específico	`reservations.blocks.subblocks`	`YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID`

Veja o estado de manutenção da capacidade física

Pode saber o estado de manutenção da sua capacidade através do Cloud Logging, das APIs e da CLI. As informações do estado de manutenção são fornecidas em quatro níveis: reserva, bloco, sub-bloco e anfitrião.

Cloud Logging

O JSON de exemplo seguinte foi gerado em resposta a esta consulta de exemplo:

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

O resultado é semelhante ao seguinte:

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

Os seguintes valores da saída descrevem as informações de manutenção:

reservationMaintenance.instanceMaintenanceOngoingCount: o número de anfitriões usados está a ser atualizado
reservationMaintenance.instanceMaintenancePendingCount: o número de anfitriões usados com manutenção pendente
reservationMaintenance.maintenanceOngoingCount: o número de anfitriões não usados está a ser atualizado
reservationMaintenance.maintenancePendingCount: o número de anfitriões não usados com manutenção pendente
reservationMaintenance.upcomingGroupMaintenance.maintenanceReasons: o tipo de manutenção
reservationMaintenance.upcomingGroupMaintenance.maintenanceStatus: o estado da operação de manutenção
reservationMaintenance.upcomingGroupMaintenance.type: o tipo de manutenção (SCHEDULED para manutenção planeada ou UNSCHEDULED para manutenção não planeada ou de emergência)
reservationMaintenance.upcomingGroupMaintenance.windowEndTime: a data/hora agendada para o fim do período da operação de manutenção
reservationMaintenance.upcomingGroupMaintenance.windowStartTime: o início agendado do período para a operação de manutenção

Configure alertas de notificação de manutenção para VMs de TPU

Pode criar alertas para eventos de manutenção nas suas VMs de TPU:

Na Google Cloud consola, aceda ao Explorador de registos.
Defina o botão Mostrar consulta para a posição "ativado".
No painel de consultas, crie uma consulta no formato indicado nas secções seguintes.
Depois de verificar se os resultados devolvidos correspondem ao que pretende, pode criar um alerta clicando no menu pendente Ações, selecionando Criar alerta de registo e preenchendo as informações no painel Criar política de alerta baseada em registos.

Consulte quando a manutenção está agendada para uma instância de VM

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

Consultar quando o período de manutenção foi aberto para uma instância de VM

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

A consulta de manutenção foi iniciada para instâncias de VM

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

Consulta para saber quando a manutenção de uma instância de VM foi concluída

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

Veja o estado de manutenção de uma VM do Cloud TPU

Pode obter o estado de manutenção de uma VM do Cloud TPU com a API de instâncias do Compute Engine ou com um comando curl a partir do sistema operativo convidado.

Descreva uma instância

gcloud

gcloud compute instances describe INSTANCE --zone ZONE

Este comando devolve um resultado semelhante ao seguinte:

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

Este comando devolve um resultado semelhante ao seguinte:

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

Também pode encontrar notificações de manutenção no Cloud Logging.

Segue-se um exemplo de uma mensagem de registo de uma manutenção planeada pendente. Para ver um exemplo de consulta, consulte o artigo Veja o estado de manutenção da capacidade física.

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

O exemplo seguinte é uma mensagem de registo de uma manutenção não planeada em curso. Para ver um exemplo de consulta, consulte Consultar quando um período de manutenção está aberto.

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

O exemplo seguinte é uma mensagem de registo para manutenção concluída. Para ver um exemplo de consulta, consulte o artigo Consulte quando a manutenção foi concluída para uma instância de 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
  },
}

Inicie manualmente a manutenção pendente da capacidade física

Assim que um evento de manutenção for agendado (maintenanceStatus estiver definido como PENDING), pode iniciar manualmente a manutenção das suas reservas, blocos ou sub-blocos que tenham a propriedade canReschedule definida como True. Quando inicia manualmente um evento de manutenção pendente, o que acontece depende do estado de manutenção da sua reserva, blocos ou sub-blocos. A tabela seguinte descreve o que acontece para cada um destes casos:

Estado de manutenção	Descrição	O que vê
Agendado	O Compute Engine tem manutenção agendada para a reserva. Pode iniciar manualmente a manutenção antes da hora agendada.	Na CLI Google Cloud ou na API REST, o campo `maintenanceStatus` está definido como `PENDING`.
Em curso	A manutenção está em curso. Não é possível reagendá-lo.	Na CLI gcloud ou na API REST, o campo `maintenanceStatus` está definido como `ONGOING`.
Concluído	A manutenção está concluída. O Compute Engine removeu todas as notificações de manutenção da VM.	Na CLI do Google Cloud ou na API REST, o campo `maintenanceStatus` não existe.

Inicie manualmente a manutenção em toda a reserva

O comando seguinte inicia a manutenção numa reserva. Use o parâmetro --scope para especificar um dos seguintes valores que especificam o âmbito da operação de manutenção:

Todos os anfitriões: --scope=all
Anfitriões com VMs em execução: --scope=running
VMs não usadas, paradas ou suspensas: --scope=unused

Para iniciar a manutenção em todos os blocos de uma reserva, execute o seguinte comando:

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

Para verificar o progresso de um evento de manutenção, execute o seguinte comando:

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

O resultado é semelhante ao seguinte:

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.

Inicie manualmente a manutenção num bloco

O comando seguinte inicia a manutenção num bloco. Use o parâmetro --scope para especificar um dos seguintes valores que especificam o âmbito da operação de manutenção:

Todos os anfitriões: --scope=all
Anfitriões com VMs em execução: --scope=running
VMs não usadas, paradas ou suspensas: --scope=unused

O comando seguinte mostra como iniciar a manutenção em anfitriões em execução:

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

O comando seguinte mostra como verificar o progresso da manutenção de um bloqueio:

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

O resultado é semelhante ao seguinte:

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

### Inicie manualmente a manutenção num sub-bloco Quando inicia a manutenção num sub-bloco, não especifica o parâmetro `--scope`, uma vez que um sub-bloco é o âmbito de manutenção mais pequeno. O comando seguinte inicia a manutenção em todos os anfitriões num bloco:

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

O comando seguinte verifica o progresso da manutenção:

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

O resultado é semelhante ao seguinte:

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

Inicie manualmente a manutenção pendente para uma VM de TPU

Se um anfitrião estiver a executar mais do que uma VM, o início da manutenção numa VM aciona a manutenção para todas as VMs no anfitrião.

O exemplo seguinte mostra como acionar manualmente a manutenção para um anfitrião do Trillium com duas VMs, vm-1 e vm-2:

gcloud compute instances perform-maintenance vm-1

O início da manutenção de vm-1 vai acionar a manutenção de vm-2.