查詢中繼資料伺服器，取得維護事件通知

中繼資料伺服器會透過 scheduling/ 中繼資料目錄清單和 maintenance-event 中繼資料金鑰，提供 Compute Engine 執行個體排程選項和設定的相關資訊。您可以使用這些中繼資料鍵瞭解 VM 的排程選項，以及即將進行的維護事件。

中繼資料伺服器會在運算執行個體即時遷移或終止前，收到維護事件通知。如要進一步瞭解維護事件和事件期間的執行個體行為，請參閱「主機維護總覽」。

對於特定 VM 集，VM 維護選項更具彈性。詳情請參閱「監控及規劃主機維護事件」。

事前準備

  • 如為 Windows Server VM，請使用 PowerShell 3.0 以上版本。建議使用 ctrl+v 貼上複製的程式碼區塊。
  • 如果尚未設定驗證，請先完成設定。 驗證程序會確認您的身分，以便授予 Google Cloud 服務和 API 的存取權。如要從本機開發環境執行程式碼或範例，您可以選取下列其中一個選項，向 Compute Engine 驗證身分：

    如要在本機開發環境中使用本頁的 Python 範例，請安裝並初始化 gcloud CLI，然後使用使用者憑證設定應用程式預設憑證。

    1. 安裝 Google Cloud CLI。

    2. 如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

    3. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

      gcloud auth application-default login

      如果您使用 Cloud Shell，則不需要執行這項操作。

      如果系統傳回驗證錯誤，且您使用的是外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

    詳情請參閱「 設定本機開發環境的驗證機制」。

接收即時遷移通知

您可以定期查詢 maintenance-event 中繼資料鍵，瞭解執行個體何時會進行即時遷移。

只有在您將 VM 的排程選項設為 migrate，或 VM 附加了 GPU 時，系統才會為維護事件填入 maintenance-event 中繼資料鍵。

這個中繼資料鍵的值會在維護事件開始前 60 秒變更，讓應用程式程式碼觸發要在維護事件前執行的任何工作，例如備份資料或更新記錄。

Compute Engine 只會在下列情況發出 60 秒警告：

  • 您已將 VM 的可用性選項設為在維護事件期間即時遷移。

  • 自上次維護事件以來，您至少查詢過一次 maintenance-event 中繼資料鍵。

    • 如果您從未查詢 maintenance-event 中繼資料鍵，或自上次遷移後未查詢中繼資料鍵，Compute Engine 會假設 VM 不需要維護事件的事前警告。維護事件會立即啟動，並略過 60 秒的警告。

    • 如不想略過 60 秒的警告，請確保用戶端程式碼在遷移事件之間，至少查詢一次 maintenance-event 中繼資料鍵。您必須直接查詢 maintenance-event 中繼資料鍵，Compute Engine 才能判斷您正在監看這個中繼資料鍵。查詢較高層級的中繼資料不會觸發提前告知。

如果 VM 連結了 GPU，這個值會在 VM 停止前 60 分鐘變更，讓您有時間關閉 VM，並在其他主機上重新啟動。連接 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 範例說明如何一併實作這兩項功能。

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。

  • 如果是單一租戶 VM，在主機維護事件期間，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 中繼資料鍵，請參閱機器系列的「維護體驗」文件。舉例來說，如要瞭解 Z3 機型的維護體驗，請參閱「Z3 執行個體的維護體驗」。

後續步驟