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

中繼資料伺服器透過 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 才能確定您正在觀察此中繼資料鍵。查詢較高層級的中繼資料並不會觸發提前通知。

對於已連結 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 範例將說明如何同時實作這兩個功能。

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、Bare Metal 執行個體，或其他不支援即時遷移的執行個體，維護事件的值會從 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 執行個體的維護體驗」。

後續步驟