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

Linux Windows

メタデータサーバーは、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. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
3. To initialize the gcloud CLI, run the following command:
```
gcloud init
```
4. 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.
  
  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
詳細については 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

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、C3D: 最長 7 日
C4D: 最長 7 日
X4: 最長 60 日
Z3: 最長 7 日

次のステップ

インスタンスの可用性ポリシーの設定方法を確認する。
ライブマイグレーションの詳細を見る。
VM メタデータの詳細を確認する。

メタデータ サーバーにクエリを実行してメンテナンス イベント通知を取得する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

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

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

Linux VM

Windows VM

Python

出力を確認する

次のステップ

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

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

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