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

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

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

針對特定組別的 VM，VM 維護選項會更具彈性。如需更多資訊，請參閱「監控及規劃主機維護事件」。

事前準備

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

  To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  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.

  For more information, see 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：最多 7 天
• C3D：最多 7 天
• X4：最長 60 天
• Z3：最多 7 天

後續步驟

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