All Capacity モードの TPU を使用したメンテナンスイベントの管理

すべての TPU ホストに定期的なメンテナンスが行われます。TPU All Capacity モードでは、今後のメンテナンスイベントを計画し、必要なときにすべての容量でメンテナンスオペレーションを開始できます。使用済み容量と未使用容量は、同時に更新することも、別々に更新することもできます。メンテナンスは、VM、サブブロック、ブロック、予約レベルで実行することもできます。このきめ細かいメンテナンス制御により、最適なメンテナンスシーケンスを作成し、ビジネスへの影響を最小限に抑えるようにメンテナンスオペレーションをスケジュールできます。

TPU All Capacity モードでは「グループ化されたメンテナンス」のみがサポートされます。つまり、予約内のすべての VM インスタンスのメンテナンスオペレーションが同時にスケジュールされます。予約内のすべての TPU VM のメンテナンスの時間枠は同じです。ただし、メンテナンスオペレーションは、ホスト、サブブロック、ブロック、予約の各レベルで個別に行うことができます。メンテナンス通知は、約 90 日前に送信されます。メンテナンスは 90 日に 1 回以上の頻度で行われることはありません。

GKE で TPU Cluster Director を使用しており、マルチホスト TPU スライスノードプールを使用している場合は、そのノードプール内のホストの保留中のメンテナンスを手動で開始する前に、GKE ノードプールを削除することをおすすめします。元のノードプール内のすべてのホストでメンテナンスが実行されたら、ノードプールを再作成できます。

TPU ホストメンテナンスイベントのタイムラインの例を次に示します。

メンテナンスがスケジュールされています。ホストが 90 日以内に更新されることを知らせる通知が送信されます。
90 日以内にホストを手動で更新することもできます。
90 日が経過すると、メンテナンスオペレーションは例外なく実行されます。
前のイベントが実行される前に別のメンテナンスイベントがスケジュールされている場合、2 番目のオペレーションは 180 日後、つまり最初のメンテナンスイベントがスケジュールされている 90 日後に実行されるようにスケジュールされます。

物理容量のメンテナンス通知アラートを設定する

Compute Engine は、スケジュールされたメンテナンス、開始されたメンテナンス、完了したメンテナンスに関する Cloud Logging イベントを送信します。これらのメンテナンスイベントはログに残るため、ログクエリを作成して容量のメンテナンスの履歴を表示できます。ログベースのアラートポリシーを作成して、予約、ブロック、サブブロックの今後のメンテナンスイベントに関する通知を受け取ることもできます。

物理容量のメンテナンスイベントのアラートを作成するには:

Google Cloud コンソールで、[ログエクスプローラ] に移動します。
[クエリを表示] がオンになっていることを確認します。
クエリペインで、次のセクションに記載されている形式でクエリを作成します。対応するパラメータのプレースホルダを適宜置き換えて、クエリを実行します。
返された結果が目的のものと一致していることを確認したら、クエリ結果ツールバーの [アクション] プルダウンから [ログアラートの作成] を選択し、リクエストされた情報を入力してアラートを作成できます。

今後のメンテナンスのクエリ

次のクエリの例は、今後のメンテナンスをクエリするものです。

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 で確認できます。メンテナンスステータス情報は、予約、ブロック、サブブロック、ホストの 4 つのレベルで提供されます。

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 のメンテナンスイベントに関するアラートを作成できます。

Google Cloud コンソールで、[ログエクスプローラ] に移動します。
[クエリを表示] 切り替えボタンをオンにします。
クエリペインで、次のセクションに記載されている形式でクエリを作成します。
返された結果が目的のものと一致することを確認したら、[アクション] プルダウンをクリックして [ログアラートの作成] を選択し、[ログベースのアラートポリシーの作成] ペインで情報を入力してアラートを作成します。

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 のメンテナンスステータスを表示する

Cloud TPU VM のメンテナンスステータスは、Compute Engine インスタンス API を使用するか、ゲストオペレーティングシステム内の curl コマンドを使用して取得できます。

インスタンスの説明を取得する

gcloud

gcloud compute instances describe <var>INSTANCE</var> --zone <var>ZONE</var>

このコマンドは、次のような出力を返します。

…
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: --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: --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 が実行されている場合、1 つの VM でメンテナンスを開始すると、ホスト上のすべての VM のメンテナンスがトリガーされます。

次の例は、2 つの VM を持つ Trillium ホストのメンテナンスを手動でトリガーする方法を示しています。

gcloud compute instances perform-maintenance vm-1

vm-1 のメンテナンスを開始すると、vm-2 のメンテナンスがトリガーされます。

All Capacity モードの TPU を使用したメンテナンス イベントの管理

物理容量のメンテナンス通知アラートを設定する

今後のメンテナンスのクエリ

メンテナンスの時間枠の開始をクエリする

完了したメンテナンスのクエリ

物理容量のメンテナンス ステータスを表示する

Cloud Logging

gcloud

TPU VM のメンテナンス通知アラートを設定する

VM インスタンスのメンテナンスがスケジュールされている日時をクエリする

VM インスタンスのメンテナンスの時間枠が継続している時刻をクエリする

VM インスタンスのメンテナンス開始をクエリする

VM インスタンスのメンテナンスの完了日時をクエリする

Cloud TPU VM のメンテナンス ステータスを表示する

インスタンスの説明を取得する

gcloud

curl

物理容量の保留中のメンテナンスを手動で開始する

予約全体でメンテナンスを手動で開始する

ブロックのメンテナンスを手動で開始する

サブブロックでメンテナンスを手動で開始する

TPU VM の保留中のメンテナンスを手動で開始する

All Capacity モードの TPU を使用したメンテナンスイベントの管理

物理容量のメンテナンスステータスを表示する

Cloud TPU VM のメンテナンスステータスを表示する