メタデータ サーバーに対してクエリを行い、メンテナンス イベント通知を取得する

メタデータ サーバーは、scheduling/ メタデータ ディレクトリ リストと maintenance-event メタデータキーを使用して、Compute Engine インスタンスのスケジューリング オプションと設定に関する情報を提供します。これらのメタデータキーを使用すると、VM のスケジューリング オプションの詳細を確認できます。また、今後のメンテナンス イベントの通知を受けることもできます。

メタデータ サーバーは、コンピューティング インスタンスのライブ マイグレーションまたは終了の前にメンテナンス イベントの通知を受信します。メンテナンス イベントとイベント中のインスタンスの動作の詳細については、ホスト メンテナンスの概要をご覧ください。

特定の VM セットの場合、VM のメンテナンスにより柔軟なオプションを使用できます。詳細については、ホスト メンテナンス イベントのモニタリングと計画をご覧ください。

始める前に

  • Windows Server VM の場合は、PowerShell 3.0 以降を使用します。コピーしたコードブロックを貼り付ける場合は ctrl+v の使用をおすすめします。
  • まだ設定していない場合は、認証を設定します。認証とは、Google Cloud サービスと API にアクセスするために ID を確認するプロセスです。ローカル開発環境からコードまたはサンプルを実行するには、次のように Compute Engine に対する認証を行います。

    ローカル開発環境でこのページの Python サンプルを使用するには、gcloud CLI をインストールして初期化し、ユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定します。

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    詳細については Set up authentication for a local development environment をご覧ください。

ライブ マイグレーションの通知を取得する

インスタンスのライブ マイグレーションが開始するタイミングを知るためには、maintenance-event メタデータキーに対するクエリを定期的に実行します。

メンテナンス イベントの発生で maintenance-event メタデータキーが更新されるのは、VM のスケジューリング オプションを migrate に設定している場合か、VM に GPU がアタッチされている場合に限ります。

このメタデータキーの値は、メンテナンス イベントが開始する 60 秒前に変更されます。アプリケーション コードで、メンテナンス イベントの発生前に実行したいタスク（データのバックアップ、ログの更新など）をトリガーできます。

Compute Engine は、次の場合にのみ 60 秒前の警告を表示します。

  • メンテナンス イベントの発生時にライブ マイグレーションを実行するように VM の可用性オプションが設定されている。

  • 前回のメンテナンス イベントの後に maintenance-event メタデータキーに対するクエリを 1 回以上実行している。

    • maintenance-event メタデータキーに対してクエリが実行されていない場合、または前回の移行後にメタデータキーにクエリが実行されていない場合、Compute Engine は VM でメンテナンス イベントの事前警告が必要ないと判断します。メンテナンス イベントはすぐに開始し、60 秒前の警告はスキップされます。

    • 60 秒前の警告がスキップされないようにするには、クライアント コードで移行イベントの合間に少なくとも 1 回 maintenance-event メタデータキーに対するクエリが実行されるようにしてください。このメタデータキーが監視されていることを Compute Engine が判断するために、maintenance-event メタデータキーに対して直接クエリを実行する必要があります。それより上位にあるメタデータのクエリでは、事前通知はトリガーされません。

GPU を接続している VM の場合は、VM が停止する 60 分前に値が変わるため、シャットダウンして別のホストで再起動する時間的余裕があります。GPU が接続している VM はライブ マイグレーションの対象外のため、インスタンスが停止します（指定があれば再起動します）。詳細については、GPU ホスト メンテナンス イベントの処理をご覧ください。

メンテナンス イベントのメタデータキーをクエリする

Linux VM

Linux VM で maintenance-event メタデータキーにクエリを実行するには、次のコマンドを実行します。

user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"

出力は次のようになります。

NONE

wait-for-change オプションを使用することもできます。このオプションを指定すると、メンテナンス イベントの開始時と終了時にのみリクエストから出力が返されます。

user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event?wait_for_change=true -H "Metadata-Flavor: Google"

Windows VM

Windows VM で maintenance-event メタデータキーにクエリを実行するには、次のコマンドを実行します。

PS C:\> 
$value = (Invoke-RestMethod `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event")
$value

出力は次のようになります。

NONE

wait-for-change オプションを使用することもできます。このオプションを指定すると、メンテナンス イベントの開始時と終了時にのみリクエストから出力が返されます。

PS C:\> 
$value = (Invoke-RestMethod `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event?wait_for_change=true")
$value

Python

maintenance-event メタデータキーを更新待機機能とともに使用すると、メンテナンス イベントの開始時と終了時にスクリプトやアプリケーションに通知できます。これにより、イベントの前後に実行するアクションを自動化できます。

次の Python サンプルは、この 2 つの機能を組み合わせて実装する方法を示しています。


import time
from typing import Callable, NoReturn, Optional

import requests


METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/"
METADATA_HEADERS = {"Metadata-Flavor": "Google"}


def wait_for_maintenance(callback: Callable[[Optional[str]], None]) -> NoReturn:
    """
    Start an infinite loop waiting for maintenance signal.

    Args:
        callback: Function to be called when a maintenance is scheduled.

    Returns:
        Never returns, unless there's an error.
    """
    url = METADATA_URL + "instance/maintenance-event"
    last_maintenance_event = None
    last_etag = "0"

    while True:
        r = requests.get(
            url,
            params={"last_etag": last_etag, "wait_for_change": True},
            headers=METADATA_HEADERS,
        )

        # During maintenance the service can return a 503, so these should
        # be retried.
        if r.status_code == 503:
            time.sleep(1)
            continue
        r.raise_for_status()

        last_etag = r.headers["etag"]

        if r.text == "NONE":
            maintenance_event = None
        else:
            maintenance_event = r.text

        if maintenance_event != last_maintenance_event:
            last_maintenance_event = maintenance_event
            callback(maintenance_event)


def maintenance_callback(event: Optional[str]) -> None:
    """
    Example callback function to handle the maintenance event.

    Args:
        event: details about scheduled maintenance.
    """
    if event:
        print(f"Undergoing host maintenance: {event}")
    else:
        print("Finished host maintenance")


def main():
    wait_for_maintenance(maintenance_callback)


if __name__ == "__main__":
    main()

出力を確認する

maintenance-event メタデータキーの初期値とデフォルト値は NONE です。

  • GPU がアタッチされている VM、ベアメタル インスタンス、またはライブ マイグレーションをサポートしていない他のインスタンスの場合、メンテナンス イベント中に値が NONE から TERMINATE_ON_HOST_MAINTENANCE に変更されます。この値は、停止イベントの開始 60 分前に更新されます。

  • GPU のない VM でスケジュール オプションが migrate に設定されている場合、maintenance-event 値は次のように変更されます。

    1. マイグレーション イベントの開始時に、値は NONE から MIGRATE_ON_HOST_MAINTENANCE に変更されます。この値は、停止イベントの開始 60 秒前に更新されます。
    2. イベントの期間中、VM インスタンスがライブ マイグレーションされている間、値は MIGRATE_ON_HOST_MAINTENANCE のままとなります。
    3. メンテナンス イベントが終了すると NONE に戻ります。

  • 単一テナントノードでは、ホスト メンテナンス イベント中、maintenance-event メタデータキーの値は変更されず、イベントの開始から終了まで NONE のままになります。

高度なメンテナンス機能をサポートするマシンシリーズでは、メンテナンス イベントの前にメタデータキー upcoming-maintenance をクエリできます。インスタンスに通知が届いている場合は、次のような値が表示されます。

{
   "maintenanceType":"SCHEDULED"
   "canReschedule": "true"
   "latestWindowStartTime": "2025-08-28T21:56:21Z"
   "maintenanceStatus": "PENDING"
   "windowEndTime": "2025-08-29T01:56:20Z"
   "windowStartTime": "2025-08-28T21:56:26Z"
}

upcoming-maintenance メタデータキーは、メンテナンス イベントの前に次のように入力されます。

  • C3: 最長 7 日
  • C3D: 最長 7 日
  • X4: 最長 60 日
  • Z3: 最長 7 日

次のステップ