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

Todos os hosts da TPU passam por manutenção regular. No modo "Toda a capacidade", você pode planejar os próximos eventos de manutenção e iniciar as operações quando quiser em toda a capacidade. Você pode 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, de um sub-bloco, de um bloco ou de uma reserva. Esse controle refinado de manutenção permite criar uma sequência ideal e programar operações de manutenção para minimizar o impacto nos negócios.

O modo de capacidade 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, sub-bloco, bloco ou reserva. As notificações de manutenção são enviadas aproximadamente 90 dias antes. A manutenção não será realizada com mais frequência do que uma vez a cada 90 dias.

Se você estiver usando o modo "Toda a capacidade" no GKE e pools de nós da fatia 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 do 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 ocorrência do evento de manutenção 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, bloco ou subbloco criando políticas de alertas com base em registros.

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

1. No console do Google Cloud , acesse a Análise 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, crie alertas selecionando Criar alerta de registro no menu suspenso Ações da barra de ferramentas "Resultados da consulta" e forneça 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:

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:

Consultar manutenções concluídas

Confira um exemplo de consulta para verificar manutenções concluídas:

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:

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

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

{
"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 compute reservations blocks describe YOUR_RESERVATION \
--block-name=YOUR_BLOCK \
--project=YOUR_PROJECT \
--zone=YOUR_ZONE

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 VMs de TPU:

1. No console do Google Cloud , acesse a Análise 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 saber 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"

Consultar a manutenção iniciada para instâncias de VM

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

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

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 de TPU da 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 compute instances describe INSTANCE --zone ZONE

…
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 http://metadata.google.internal/computeMetadata/v1/instance/upcoming-maintenance?alt=json -H "Metadata-Flavor: Google"

{
"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": "ONGOING"
      "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 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 para 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:

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 organizadores: --scope=all
• Hosts com VMs em execução: --scope=running
• VMs não utilizadas, 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á o 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.

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 organizadores: --scope=all
• Hosts com VMs em execução: --scope=running
• VMs não utilizadas, interrompidas ou suspensas: --scope=unused

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

gcloud compute reservations blocks perform-maintenance YOUR_RESERVATION \
    --block-name=YOUR_BLOCK_NAME \
    --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á o seguinte:

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 sub-bloco, não é necessário especificar o parâmetro --scope porque um sub-bloco é 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á o 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

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. Para informações sobre como iniciar manualmente um evento de manutenção para uma VM de TPU, consulte Iniciar manualmente um evento de manutenção de host na documentação do Compute Engine.