以「所有容量」模式管理 TPU 的維護事件

所有 TPU 主機都會定期維護。在 TPU 全容量模式中，您可以規劃即將執行的維護事件，並在需要時對所有容量啟動維護作業。您可以同時或分別更新已用和未用的容量。您也可以在 VM、子區塊、區塊或預留項目層級執行維護作業。透過這項精細的維護控制功能，您可以建立最佳維護順序，並排定維護作業時間，盡量減少對業務的影響。

TPU All Capacity 模式僅支援「分組維護」，也就是說，系統會為預留項目中的所有 VM 執行個體，同時排定維護作業。預留項目中的所有 TPU VM 都會共用相同的維護時段。 不過，維護作業可以在主機、子區塊、區塊或預留項目層級分別執行。維護通知會在約 90 天前發送。維護作業的執行頻率不會超過每 90 天一次。

如果您在 GKE 上使用 TPU Cluster Director，且使用多主機 TPU 配量節點集區，建議您先刪除 GKE 節點集區，再手動啟動該節點集區中任何主機的待處理維護作業。原始節點集區中的所有主機都執行維護作業後，即可重新建立節點集區。

以下是 TPU 主機維護事件的範例時間表：

  1. 已排定維護作業。系統會傳送通知，告知你主機將在 90 天內更新。
  2. 你也可以選擇在 90 天內手動更新主機。
  3. 90 天後，系統會一律執行維護作業。
  4. 如果排定在先前維護活動執行前進行其他維護活動，則第二次作業會在 180 天後執行，也就是排定初始維護活動後 90 天。

設定實體容量的維護通知快訊

Compute Engine 會在排定、開始或完成維護作業時，傳送 Cloud Logging 事件。這些維護事件會保留在記錄中，方便您建立記錄查詢，查看容量維護的歷史記錄。您也可以建立以記錄為準的警示政策，接收預訂、區塊或子區塊的未來維護事件通知。

如要為實體容量的維護事件建立快訊，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Logs Explorer」。
  2. 確認「顯示查詢」已開啟。
  3. 在查詢窗格中，以以下各節列出的格式建立查詢。請視情況替換對應的參數預留位置，然後執行查詢。
  4. 確認傳回的結果符合需求後，即可建立快訊。方法是從查詢結果工具列的「動作」下拉式選單中選取「建立記錄快訊」，然後提供所需資訊。

查詢即將執行的維護作業

以下是查詢近期維護作業的範例查詢：

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

將 CAPACITY_COMPONENT 和 RESOURCE_NAME 替換為下列值：

接收以下項目的近期維護通知： CAPACITY_COMPONENT RESOURCE_NAME
所有預留項目 reservations 省略 RESOURCE_NAME
特定預留項目 reservations YOUR_RESERVATION_NAME
所有預留項目的區塊 reservations.blocks 省略 RESOURCE_NAME
特定區塊 reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
所有預留項目的子區塊 reservations.blocks.subblocks 省略 RESOURCE_NAME
特定子模塊 reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

查詢維護期間開放時間

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

將 CAPACITY_COMPONENT 替換為下列其中一個值：

接收以下維護期間的通知： CAPACITY_COMPONENT
預留項目中的區塊 reservations.blocks
預留項目中的子模塊 reservations.blocks.subblocks

查詢已完成的維護作業

以下是查詢已完成維護作業的範例查詢：

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

將 CAPACITY_COMPONENT 和 RESOURCE_NAME 替換為下列值：

接收以下項目的維護完成通知： CAPACITY_COMPONENT RESOURCE_NAME
所有預留項目 reservations 省略 RESOURCE_NAME
特定預留項目 reservations YOUR_RESERVATION_NAME
所有預留項目的區塊 reservations.blocks 省略 RESOURCE_NAME
特定區塊 reservations.blocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID
所有預留項目的子區塊 reservations.blocks.subblocks 省略 RESOURCE_NAME
特定子模塊 reservations.blocks.subblocks YOUR_RESERVATION_NAME/reservationBlocks/YOUR_RESERVATION_BLOCK_ID/reservationSubBlocks/YOUR_RESERVATION_SUBBLOCK_ID

查看實體容量的維護狀態

您可以透過 Cloud Logging、API 和 CLI 瞭解容量的維護狀態。維護狀態資訊分為四個層級：預訂、區塊、子區塊和主機。

Cloud Logging

下列 JSON 範例是針對這個範例查詢所產生：

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

輸出結果會與下列內容相似：

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

輸出內容中的下列值說明維護資訊：

  • reservationMaintenance.instanceMaintenanceOngoingCount：正在更新的使用主機數量
  • reservationMaintenance.instanceMaintenancePendingCount：待維護的使用中主機數量
  • reservationMaintenance.maintenanceOngoingCount：正在更新的未使用主機數量
  • reservationMaintenance.maintenancePendingCount：待維護的閒置主機數量
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceReasons：維護作業類型
  • reservationMaintenance.upcomingGroupMaintenance.maintenanceStatus：維護作業的狀態
  • reservationMaintenance.upcomingGroupMaintenance.type：維護類型 (SCHEDULED 代表預先排定的維護作業，UNSCHEDULED 則代表非預先排定或緊急維護作業)
  • reservationMaintenance.upcomingGroupMaintenance.windowEndTime：維護作業預計結束的時間範圍
  • reservationMaintenance.upcomingGroupMaintenance.windowStartTime：維護作業排定的時間範圍開始時間

為 TPU VM 設定維護通知快訊

您可以為 TPU VM 上的維護事件建立快訊：

  1. 前往 Google Cloud 控制台的「Logs Explorer」。
  2. 將「顯示查詢」切換鈕設為「開啟」。
  3. 在查詢窗格中，以以下各節列出的格式建立查詢。
  4. 確認傳回的結果符合需求後，請按一下「動作」下拉式選單，選取「建立記錄檔快訊」，然後在「建立以記錄為準的快訊政策」窗格中填寫資訊，即可建立快訊。

查詢 VM 執行個體排定的維護時間

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

查詢 VM 執行個體維護期間的開啟時間

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

已開始查詢 VM 執行個體的維護作業

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

查詢 VM 執行個體維護作業完成時間

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

查看 Cloud TPU VM 的維護狀態

您可以使用 Compute Engine 執行個體 API，或從客層作業系統內執行 curl 指令，擷取 Cloud TPU VM 的維護狀態。

描述執行個體

gcloud

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

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

您也可以在 Cloud Logging 中查看維護通知。

以下是待處理的計畫性維護作業記錄訊息範例。如需查詢範例，請參閱「查看實體容量的維護狀態」。

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

以下範例是正在進行的非預期維護作業記錄訊息。如需查詢範例，請參閱「查詢維護期間何時開放」。

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

以下範例是維護作業完成的記錄訊息。如需查詢範例，請參閱查詢 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
  },
}

手動啟動實體容量的待處理維護作業

排定維護作業 (maintenanceStatus 設為 PENDING) 後，您可以手動為 canReschedule 屬性設為 True 的預訂、區塊或子區塊啟動維護作業。手動啟動待處理的維護事件時，會發生什麼情況取決於預留項目、區塊或子區塊的維護狀態。下表說明每種情況的後續處理方式：

維護狀態 說明 顯示內容
已排定 Compute Engine 已排定預留資源的維護作業。您可以在排定的時間之前，手動啟動維護作業。 在 Google Cloud CLI 或 REST API 中，maintenanceStatus 欄位會設為 PENDING。
進行中 維護作業正在進行中。你無法重新安排發布時程。 在 Google Cloud CLI 或 REST API 中，maintenanceStatus 欄位會設為 ONGOING。
完成 維護作業已完成。Compute Engine 已從 VM 中移除所有維護通知。 在 Google Cloud CLI 或 REST API 中，maintenanceStatus 欄位不存在。

手動對整個預留項目啟動維護作業

下列指令會啟動預訂項目的維護作業。使用 --scope 參數指定下列其中一個值，以指定維護作業的範圍：

  • 所有主機：--scope=all
  • 有執行中 VM 的主機：--scope=running
  • 未使用的 VM、已停止的 VM 或已暫停的 VM：--scope=unused

如要對預留項目中的所有區塊啟動維護作業，請執行下列指令：

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

如要查看維護事件的進度，請執行下列指令：

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

輸出結果會與下列內容相似：

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.

手動啟動模塊維護作業

下列指令會啟動區塊的維護作業。使用 --scope 參數指定下列其中一個值，以指定維護作業的範圍：

  • 所有主機：--scope=all
  • 有執行中 VM 的主機：--scope=running
  • 未使用的 VM、已停止的 VM 或已暫停的 VM：--scope=unused

以下指令顯示如何對執行中的主機啟動維護作業：

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

以下指令顯示如何檢查區塊的維護進度：

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

輸出結果會與下列內容相似：

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

手動啟動子模塊維護作業

對子區塊啟動維護作業時，您不需要指定 --scope 參數，因為子區塊是最小的維護範圍。

下列指令會啟動區塊中所有主機的維護作業：

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

下列指令會檢查維護作業進度：

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

輸出結果會與下列內容相似：

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

手動啟動 TPU VM 的待處理維護作業

如果主機執行多個 VM，啟動其中一個 VM 的維護作業，會觸發主機上所有 VM 的維護作業。

以下範例說明如何手動觸發維護作業，適用於有兩個 VM 的 Trillium 主機，分別是 vm-1 和 vm-2：

gcloud compute instances perform-maintenance vm-1

開始維護 vm-1 時，系統會一併維護 vm-2。