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

中繼資料伺服器透過 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. 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 中繼資料鍵，瞭解執行個體何時即將進行即時遷移。

只有在您已將 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 主機維護事件」。

查詢維護事件中繼資料鍵

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

NONE

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

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

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 分鐘更新。

• 對於排程選項為 migrate 的非 GPU VM，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 中繼資料鍵，如下所示：

• C3、C3D：最多 7 天
• C4D：最多 7 天
• X4：最多 60 天
• Z3：最多 7 天

後續步驟

• 瞭解如何設定執行個體可用性政策。
• 進一步瞭解即時遷移。
• 進一步瞭解 VM 中繼資料。