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

Linux Windows

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

デフォルトでは、すべての VM（Z3 を除く）がライブマイグレーションに設定されています。メタデータサーバーは、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.
詳細については、ローカル開発環境の認証の設定をご覧ください。

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

メンテナンスイベントの発生時に通知を受けるようにするには、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 ホストメンテナンスイベントの処理をご覧ください。

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

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

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 のままになります。

次のステップ

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

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

始める前に

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

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

Linux VM

Windows VM

Python

出力を確認する

次のステップ

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

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

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