Gestionar eventos de mantenimiento con TPUs en el modo Toda la capacidad

Todos los hosts de TPU se someten a un mantenimiento periódico. En el modo de toda la capacidad de las TPUs, puedes planificar los próximos eventos de mantenimiento e iniciar las operaciones de mantenimiento cuando quieras en toda tu capacidad. Puede actualizar la capacidad utilizada y sin usar simultáneamente o por separado. También puedes realizar tareas de mantenimiento a nivel de máquina virtual, subbloque, bloque o reserva. Este control de mantenimiento detallado te permite crear una secuencia de mantenimiento óptima y programar operaciones de mantenimiento para minimizar el impacto en la empresa.

El modo de capacidad total de TPU solo admite el mantenimiento agrupado, lo que significa que las operaciones de mantenimiento de todas las instancias de VM de una reserva se programan al mismo tiempo. Todas las VMs de TPU de una reserva tienen la misma ventana de mantenimiento. Sin embargo, las operaciones de mantenimiento se pueden llevar a cabo por separado a nivel de host, subbloque, bloque o reserva. Las notificaciones de mantenimiento se envían con aproximadamente 90 días de antelación. El mantenimiento no se llevará a cabo con una frecuencia superior a una vez cada 90 días.

Si usas TPU Cluster Director en GKE y grupos de nodos de slices de TPU multihost, te recomendamos que elimines el grupo de nodos de GKE antes de iniciar manualmente el mantenimiento pendiente de cualquier host de ese grupo de nodos. Una vez que se haya realizado el mantenimiento en todos los hosts del grupo de nodos original, puedes volver a crear el grupo de nodos.

A continuación, se muestra un ejemplo de cronología de un evento de mantenimiento de host de TPU:

  1. El mantenimiento está programado. Se te enviará una notificación para informarte de que el host se actualizará en un plazo de 90 días.
  2. Puedes actualizar manualmente el host en un plazo de 90 días.
  3. Al cabo de 90 días, la operación de mantenimiento se ejecuta sin excepción.
  4. Si se programa otro evento de mantenimiento antes de que se ejecute el anterior, la segunda operación se programará para que se ejecute 180 días después, es decir, 90 días después de que se programe el evento de mantenimiento inicial.

Configurar alertas de notificación de mantenimiento para la capacidad física

Compute Engine te envía eventos de Cloud Logging cuando se programa, se inicia o se completa el mantenimiento. Estos eventos de mantenimiento permanecen en tus registros para que puedas crear consultas de registro y obtener un historial del mantenimiento de tu capacidad. También puedes recibir notificaciones sobre futuros eventos de mantenimiento de una reserva, un bloque o un subbloque creando políticas de alertas basadas en registros.

Para crear una alerta de eventos de mantenimiento en tu capacidad física, sigue estos pasos:

  1. En la Google Cloud consola, ve al Explorador de registros.
  2. Asegúrate de que la opción Mostrar consulta esté activada.
  3. En el panel de consultas, crea una consulta con el formato que se indica en las secciones siguientes. Sustituye el marcador de posición del parámetro correspondiente y ejecuta la consulta.
  4. Una vez que hayas verificado que los resultados devueltos coinciden con lo que quieres, puedes crear alertas seleccionando Crear alerta de registro en el menú desplegable Acciones de la barra de herramientas Resultados de la consulta y proporcionando la información solicitada.

Consultar el mantenimiento programado

A continuación, se muestra un ejemplo de consulta para buscar el mantenimiento programado:

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

Sustituye CAPACITY_COMPONENT y RESOURCE_NAME por los siguientes valores:

Recibir una notificación de mantenimiento programado para CAPACITY_COMPONENT RESOURCE_NAME
Todas las reservas reservations Omitir RESOURCE_NAME
Una reserva específica reservations YOUR_RESERVATION_NAME
Bloqueos en todas las reservas reservations.blocks Omitir RESOURCE_NAME
Un bloque específico reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
Subbloques en todas las reservas reservations.blocks.subblocks Omitir RESOURCE_NAME
Un subbloque específico reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

Consulta para abrir la ventana de mantenimiento

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

Sustituye CAPACITY_COMPONENT por uno de los siguientes valores:

Recibir una notificación cuando se abra una ventana de mantenimiento para CAPACITY_COMPONENT
Bloqueos en una reserva reservations.blocks
Subbloques de una reserva reservations.blocks.subblocks

Consulta de mantenimiento completado

A continuación, se muestra un ejemplo de consulta para buscar el mantenimiento completado:

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

Sustituye CAPACITY_COMPONENT y RESOURCE_NAME por los siguientes valores:

Recibir notificaciones de mantenimiento completado de CAPACITY_COMPONENT RESOURCE_NAME
Todas las reservas reservations Omitir RESOURCE_NAME
Una reserva específica reservations YOUR_RESERVATION_NAME
Bloqueos en todas las reservas reservations.blocks Omitir RESOURCE_NAME
Un bloque específico reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
Subbloques en todas las reservas reservations.blocks.subblocks Omitir RESOURCE_NAME
Un subbloque específico reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

Ver el estado de mantenimiento de la capacidad física

Puedes consultar el estado de mantenimiento de tu capacidad a través de Cloud Logging, las APIs y la CLI. La información sobre el estado del mantenimiento se proporciona en cuatro niveles: reserva, bloque, subbloque y host.

Cloud Logging

El siguiente ejemplo de JSON se ha generado en respuesta a esta consulta de ejemplo:

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

El resultado debería ser similar al siguiente:

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

Los siguientes valores de la salida describen la información de mantenimiento:

  • reservationMaintenance.instanceMaintenanceOngoingCount: número de hosts usados que se están actualizando
  • reservationMaintenance.instanceMaintenancePendingCount: número de hosts usados pendientes de mantenimiento
  • reservationMaintenance.maintenanceOngoingCount: número de hosts no utilizados que se están actualizando
  • reservationMaintenance.maintenancePendingCount: número de hosts sin usar pendientes de mantenimiento
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceReasons: el tipo de mantenimiento
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceStatus: el estado de la operación de mantenimiento
  • reservationMaintenance.upcomingGroupMaintenance.type: el tipo de mantenimiento (SCHEDULED si es un mantenimiento programado o UNSCHEDULED si es un mantenimiento no programado o de emergencia)
  • reservationMaintenance.upcomingGroupMaintenance.windowEndTime: la hora de finalización programada de la ventana de tiempo de la operación de mantenimiento.
  • reservationMaintenance.upcomingGroupMaintenance.windowStartTime: hora de inicio programada de la ventana de tiempo de la operación de mantenimiento.

Configurar alertas de notificaciones de mantenimiento para VMs de TPU

Puedes crear alertas para los eventos de mantenimiento de tus VMs de TPU:

  1. En la Google Cloud consola, ve al Explorador de registros.
  2. Activa el interruptor Mostrar consulta.
  3. En el panel de consultas, crea una consulta con el formato que se indica en las secciones siguientes.
  4. Una vez que hayas verificado que los resultados devueltos coinciden con lo que quieres, puedes crear una alerta haciendo clic en el menú desplegable Acciones, seleccionando Crear alerta de registro y completando la información del panel Crear política de alertas basada en registros.

Consultar cuándo se ha programado el mantenimiento de una instancia de VM

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

Consulta cuándo se ha abierto la ventana de mantenimiento de una instancia de VM

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

Consulta de mantenimiento iniciada para instancias de VM

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

Consulta para saber cuándo se ha completado el mantenimiento de una instancia de VM

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

Ver el estado de mantenimiento de una VM de TPU de Cloud

Puedes consultar el estado de mantenimiento de una VM de Cloud TPU con la API de instancias de Compute Engine o con un comando curl desde el sistema operativo invitado.

Describe una instancia

gcloud

gcloud compute instances describe INSTANCE --zone ZONE

Este comando devuelve un resultado como el siguiente:

…
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 devuelve un resultado como el siguiente:

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

También puedes encontrar notificaciones de mantenimiento en Cloud Logging.

A continuación, se muestra un ejemplo de mensaje de registro de un mantenimiento programado pendiente. Para ver un ejemplo de consulta, consulta Ver el estado de mantenimiento de la capacidad 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
  },
}

El siguiente ejemplo es un mensaje de registro de un mantenimiento no planificado en curso. Para ver un ejemplo de consulta, consulta Consultar cuándo está abierta una ventana de mantenimiento.

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

El siguiente ejemplo es un mensaje de registro de mantenimiento completado. Para ver un ejemplo de consulta, consulta Consulta para saber cuándo se ha completado el mantenimiento de una instancia 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
  },
}

Iniciar manualmente el mantenimiento pendiente de la capacidad física

Una vez que se haya programado un evento de mantenimiento (el valor de maintenanceStatus es PENDING), puedes iniciar manualmente el mantenimiento de tus reservas, bloques o subbloques que tengan la propiedad canReschedule definida como True. Cuando inicias manualmente un evento de mantenimiento pendiente, lo que ocurre depende del estado de mantenimiento de tu reserva, bloques o subbloques. En la siguiente tabla se describe lo que ocurre en cada caso:

Estado de mantenimiento Descripción Lo que ves
Programado Compute Engine ha programado una tarea de mantenimiento para la reserva. Puedes iniciar el mantenimiento manualmente antes de la hora programada. En la API REST o Google Cloud CLI, el campo maintenanceStatus se define como PENDING.
En curso Se está llevando a cabo el mantenimiento. No puedes volver a programarlo. En Google Cloud CLI o en la API REST, el campo maintenanceStatus se define como ONGOING.
Completado El mantenimiento ha finalizado. Compute Engine ha eliminado todas las notificaciones de mantenimiento de la máquina virtual. En la CLI de Google Cloud o en la API REST, el campo maintenanceStatus no existe.

Iniciar manualmente el mantenimiento de toda la reserva

El siguiente comando inicia el mantenimiento de una reserva. Usa el parámetro --scope para especificar uno de los siguientes valores que definen el ámbito de la operación de mantenimiento:

  • Todos los hosts: --scope=all
  • Hosts con VMs en ejecución: --scope=running
  • Máquinas virtuales sin usar, detenidas o suspendidas: --scope=unused

Para iniciar el mantenimiento de todos los bloques de una reserva, ejecuta el siguiente comando:

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

Para comprobar el progreso de un evento de mantenimiento, ejecuta el siguiente comando:

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

El resultado debería ser similar al siguiente:

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 el mantenimiento de un bloque

El siguiente comando inicia el mantenimiento de un bloque. Usa el parámetro --scope para especificar uno de los siguientes valores que definen el ámbito de la operación de mantenimiento:

  • Todos los hosts: --scope=all
  • Hosts con VMs en ejecución: --scope=running
  • Máquinas virtuales sin usar, detenidas o suspendidas: --scope=unused

El siguiente comando muestra cómo iniciar el mantenimiento en los hosts en ejecución:

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

El siguiente comando muestra cómo comprobar el progreso del mantenimiento de un bloque:

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

El resultado debería ser similar al siguiente:

ResourceStatus
  upcomingGroupMaintenance:
    "maintenanceType":"SCHEDULED"
…
    "maintenanceGroupStatus":"PENDING" → "ONGOING"
    "maintenancePending":0
 "maintenanceOngoing":70 → 0
 ### Iniciar manualmente el mantenimiento de un subbloque Cuando inicias el mantenimiento de un subbloque, no especificas el parámetro `--scope` porque un subbloque es el ámbito de mantenimiento más pequeño. El siguiente comando inicia el mantenimiento en todos los hosts de un bloque: 
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

El siguiente comando comprueba el progreso del mantenimiento:

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

El resultado debería ser similar al siguiente:

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 el mantenimiento pendiente de una máquina virtual de TPU

Si un host ejecuta más de una VM, al iniciar el mantenimiento de una VM, se activará el mantenimiento de todas las VMs del host.

En el siguiente ejemplo se muestra cómo activar manualmente el mantenimiento de un host de Trillium que tiene dos máquinas virtuales, vm-1 y vm-2:

gcloud compute instances perform-maintenance vm-1

Si se inicia el mantenimiento de vm-1, se activará el mantenimiento de vm-2.