Gerenciar eventos de manutenção com TPUs no modo "Toda a capacidade"

Todos os hosts da TPU passam por manutenção regular. No modo de capacidade total da TPU, é possível planejar os próximos eventos de manutenção e iniciar as operações quando quiser em toda a capacidade. É possível atualizar a capacidade usada e não usada simultaneamente ou separadamente. Também é possível realizar a manutenção no nível de uma VM, um sub-bloco, um bloco ou uma reserva. Esse controle refinado permite criar uma sequência de manutenção ideal e programar operações de manutenção para minimizar o impacto nos negócios.

O modo de capacidade total da TPU só é compatível com "manutenção agrupada", o que significa que as operações de manutenção de todas as instâncias de VM em uma reserva são programadas ao mesmo tempo. Todas as VMs de TPU em uma reserva têm a mesma janela de manutenção. No entanto, as operações de manutenção podem ser realizadas separadamente no nível do host, 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 será realizada com mais frequência do que uma vez a cada 90 dias.

Se você estiver usando o TPU Cluster Director no GKE e pools de nós da fração da TPU de vários hosts, recomendamos excluir o pool de nós do GKE antes de iniciar manualmente a manutenção pendente de qualquer host nesse pool. Depois que a manutenção for executada em todos os hosts no pool de nós original, você poderá recriar o pool.

Confira a seguir um exemplo de linha do tempo para um evento de manutenção de host da TPU:

  1. A manutenção está programada. Você vai receber uma notificação informando que o host será atualizado em até 90 dias.
  2. Você pode atualizar manualmente o host com 90 dias.
  3. Após 90 dias, a operação de manutenção é executada sem exceção.
  4. Se outro evento de manutenção for programado antes da execução do anterior, a segunda operação será programada para ser executada após 180 dias, 90 dias após a programação do evento inicial.

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

O Compute Engine envia eventos do Cloud Logging para manutenção programada, iniciada ou concluída. Esses eventos de manutenção permanecem nos seus registros para que você possa criar consultas de registros e ter uma visão histórica da manutenção da sua capacidade. Você também pode receber notificações sobre eventos de manutenção futuros para uma reserva, um bloco ou um subbloco criando políticas de alerta com base em registros.

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

  1. No console do Google Cloud , acesse o Explorador de registros.
  2. Verifique se a opção Mostrar consulta está ativada.
  3. No painel de consulta, crie uma consulta no formato listado nas seções a seguir. Substitua o marcador de posição do parâmetro correspondente e execute a consulta.
  4. Depois de verificar se os resultados retornados correspondem ao que você quer, é possível criar alertas selecionando Criar alerta de registro no menu suspenso Ações da barra de ferramentas "Resultados da consulta" e fornecendo as informações solicitadas.

Consultar manutenções futuras

Confira a seguir um exemplo de consulta para manutenção programada:

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:

Receber notificações 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 abertura da janela de manutenção

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

Substitua CAPACITY_COMPONENT por um dos seguintes valores:

Receber notificação sobre a abertura de uma janela de manutenção para CAPACITY_COMPONENT
Blocos em uma reserva reservations.blocks
Sub-blocos em uma reserva reservations.blocks.subblocks

Consultar manutenções concluídas

Confira um exemplo de consulta para 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:

Receber notificação de manutenção concluída 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

Ver o status de manutenção da capacidade física

É possível conferir o status de manutenção da sua capacidade no Cloud Logging, APIs e CLI. As informações de status da manutenção são fornecidas em quatro níveis: reserva, bloco, subbloco e host.

Cloud Logging

O exemplo de JSON a seguir 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 será assim:

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 valores a seguir da saída descrevem as informações de manutenção:

  • reservationMaintenance.instanceMaintenanceOngoingCount: o número de hosts usados que estão sendo atualizados.
  • reservationMaintenance.instanceMaintenancePendingCount: o número de hosts usados com manutenção pendente
  • reservationMaintenance.maintenanceOngoingCount: o número de hosts não utilizados que estão sendo atualizados.
  • reservationMaintenance.maintenancePendingCount: o número de hosts não utilizados pendentes de manutenção.
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceReasons: o tipo de manutenção
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceStatus: o status da operação de manutenção
  • reservationMaintenance.upcomingGroupMaintenance.type: o tipo de manutenção (SCHEDULED para manutenção planejada ou UNSCHEDULED para manutenção não planejada ou de emergência)
  • reservationMaintenance.upcomingGroupMaintenance.windowEndTime: o fim programado do intervalo de tempo para a operação de manutenção.
  • reservationMaintenance.upcomingGroupMaintenance.windowStartTime: o início programado do intervalo de tempo para a operação de manutenção.

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

É possível criar alertas para eventos de manutenção nas suas VMs de TPU:

  1. No console do Google Cloud , acesse o Explorador de registros.
  2. Defina o botão Mostrar consulta como "ativado".
  3. No painel de consulta, crie uma consulta no formato listado nas seções a seguir.
  4. Depois de verificar se os resultados retornados correspondem ao que você quer, crie um alerta clicando no menu suspenso Ações, selecione Criar alerta de registro e preencha as informações no painel Criar política de alertas com base em registros.

Consultar quando a manutenção está programada para uma instância de VM

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

Consulta para quando a janela de manutenção foi aberta para uma instância de VM

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

Consulta para manutenção iniciada em instâncias de VM

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

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

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

Conferir o status de manutenção de uma VM do Cloud TPU

É possível recuperar o status de manutenção de uma VM do Cloud TPU com a API de instância do Compute Engine ou com um comando curl no sistema operacional convidado.

Descrever uma instância

gcloud 

gcloud compute instances describe INSTANCE --zone ZONE

Esse comando retorna uma saída semelhante a esta:

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

Esse comando retorna uma saída semelhante a esta:

{
"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 é possível encontrar notificações de manutenção no Cloud Logging.

Confira a seguir um exemplo de mensagem de registro de uma manutenção planejada pendente. Para ver um exemplo de consulta, consulte Conferir o status 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 a seguir é uma mensagem de registro de uma manutenção não planejada em andamento. Para ver um exemplo de consulta, consulte Consultar quando uma janela de manutenção está aberta.

{
  "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 a seguir é uma mensagem de registro para uma manutenção concluída. Para um exemplo de consulta, consulte Consultar quando a manutenção de uma instância de VM foi concluída.

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

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

Depois que um evento de manutenção é programado (maintenanceStatus é definido como PENDING), é possível iniciar manualmente a manutenção das suas reservas, blocos ou sub-blocos que têm a propriedade canReschedule definida como True. Quando você inicia manualmente um evento de manutenção pendente, o que acontece depende do estado de manutenção da reserva, dos blocos ou dos sub-blocos. A tabela a seguir descreve o que acontece em cada um deles:

Estado de manutenção Descrição O que você vê
Programado O Compute Engine tem uma manutenção programada para a reserva. É possível iniciar a manutenção manualmente antes do horário programado. Na CLI do Google Cloud ou na API REST, o campo maintenanceStatus é definido como PENDING.
Em andamento A manutenção está em andamento. Não é possível reagendar. Na CLI do Google Cloud ou na API REST, o campo maintenanceStatus é definido como ONGOING.
Concluído A manutenção foi 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.

Iniciar manualmente a manutenção em toda a reserva

O comando a seguir inicia a manutenção de uma reserva. Use o parâmetro --scope para especificar um dos seguintes valores que definem o escopo da operação de manutenção:

  • Todos os hosts: --scope=all
  • Hosts com VMs em execução: --scope=running
  • VMs não usadas, interrompidas 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 será assim:

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.

Iniciar manualmente a manutenção em um bloco

O comando a seguir inicia a manutenção em um bloco. Use o parâmetro --scope para especificar um dos seguintes valores que definem o escopo da operação de manutenção:

  • Todos os hosts: --scope=all
  • Hosts com VMs em execução: --scope=running
  • VMs não usadas, interrompidas ou suspensas: --scope=unused

O comando a seguir mostra como iniciar a manutenção em hosts em execução:

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

O comando a seguir mostra como verificar o progresso da manutenção de um bloco:

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

O resultado será assim:

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

Iniciar manualmente a manutenção em um sub-bloco

Ao iniciar a manutenção em um subbloco, não é necessário especificar o parâmetro --scope, porque um subbloco é o menor escopo de manutenção.

O comando a seguir inicia a manutenção em todos os hosts de um 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 a seguir 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 será assim:

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

Iniciar manualmente a manutenção pendente de uma VM de TPU

Se um host estiver executando mais de uma VM, iniciar a manutenção em uma delas vai acionar a manutenção de todas as VMs no host.

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

gcloud compute instances perform-maintenance vm-1

Iniciar a manutenção de vm-1 vai acionar a manutenção de vm-2.