שליחת שאילתה לשרת המטא-נתונים לגבי הודעות על אירועי תחזוקה

שרת המטא-נתונים מספק מידע על אפשרויות התזמון וההגדרות של מכונה ב-Compute Engine, באמצעות רשימת הספרייה של המטא-נתונים [scheduling/] ומפתח המטא-נתונים [maintenance-event]. אפשר להשתמש במפתחות המטא-נתונים האלה כדי לקבל מידע על אפשרויות התזמון של מכונה וירטואלית, וגם כדי לקבל התראה על אירוע תחזוקה עתידי.

שרת המטא-נתונים מקבל הודעות על אירועי תחזוקה לפני שמבצעים מיגרציה פעילה או סיום של מכונת Compute. במאמר סקירה כללית על תחזוקת מארח מוסבר בהרחבה על אירועי תחזוקה ועל ההתנהגות של המכונות במהלך האירועים.

אם יש לכם קבוצה ספציפית של מכונות VM, האפשרויות שלכם לתחזוקת מכונות VM גמישות יותר. מידע נוסף זמין במאמר מעקב ותכנון של אירוע תחזוקה של מארח.

לפני שמתחילים

  • במכונות וירטואליות של Windows Server, צריך להשתמש ב-PowerShell 3.0 ואילך. מומלץ להשתמש ב-ctrl+v כדי להדביק את בלוקי הקוד שהועתקו.
  • אם עדיין לא עשיתם את זה, תצטרכו להגדיר אימות. אימות הוא תהליך שבו מאמתים את הזהות שלכם כדי לקבל גישה לממשקי API ולשירותים של Google Cloud . כדי להריץ קוד או דוגמאות מסביבת פיתוח מקומית, אפשר לבצע אימות ל-Compute Engine באחת מהדרכים הבאות:

    כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של Python שבדף הזה, מתקינים ומפעילים את ה-CLI של gcloud, ואז מגדירים את Application Default Credentials באמצעות פרטי הכניסה של המשתמש.

    1. התקינו את ה-CLI של Google Cloud.

    2. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

    3. אם אתם משתמשים במעטפת מקומית, צרו פרטי כניסה לאימות מקומי בחשבון המשתמש: 

      gcloud auth application-default login

      אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

      אם מוחזרת שגיאת אימות ואתם משתמשים בספק זהויות חיצוני (IdP), ודאו ש נכנסתם ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

    למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

קבלת התראות בזמן אמת על מיגרציה פעילה

כדי לדעת מתי תתבצע מיגרציה פעילה של המופע שלכם, צריך לשלוח שאילתה למפתח המטא-נתונים maintenance-event באופן תקופתי.

מפתח המטא-נתונים maintenance-event מאוכלס לאירועי תחזוקה רק אם הגדרתם את אפשרות התזמון של המכונה הווירטואלית ל-migrate או אם למכונה הווירטואלית מצורף GPU.

הערך של מפתח המטא-נתונים הזה משתנה 60 שניות לפני שמתחיל אירוע תחזוקה, וכך קוד האפליקציה יכול להפעיל משימות שרוצים לבצע לפני אירוע תחזוקה, כמו גיבוי נתונים או עדכון יומנים.

האזהרה של 60 שניות מופיעה ב-Compute Engine רק אם:

  • הגדרתם את אפשרויות הזמינות של המכונה הווירטואלית למיגרציה פעילה במהלך אירוע תחזוקה.

  • הפעלת שאילתה לגבי מפתח המטא-נתונים maintenance-event לפחות פעם אחת מאז אירוע התחזוקה האחרון.

    • אם אף פעם לא שלחתם שאילתה לגבי מפתח המטא-נתונים maintenance-event או שלא שלחתם שאילתה לגבי מפתח המטא-נתונים מאז ההעברה האחרונה, מערכת Compute Engine מניחה שהמכונה הווירטואלית לא דורשת אזהרה מראש לגבי אירועי תחזוקה. אירוע התחזוקה מתחיל באופן מיידי, בלי אזהרה של 60 שניות.

    • אם אתם לא רוצים לדלג על האזהרה של 60 השניות, ודאו שקוד הלקוח שולח שאילתה למפתח המטא-נתונים maintenance-event לפחות פעם אחת בין אירועי ההעברה. כדי ש-Compute Engine יקבע שאתם צופים במפתח המטא-נתונים הזה, אתם צריכים לבצע שאילתה ישירות על מפתח המטא-נתונים maintenance-event. שאילתה של מטא-נתונים ברמה גבוהה יותר לא מפעילה את ההודעה מראש.

במכונות וירטואליות עם יחידות GPU מצורפות, הערך משתנה 60 דקות לפני שהמכונות הווירטואליות נעצרות, כדי שיהיה לכם זמן לכבות ולהפעיל מחדש במארח אחר. מכונות וירטואליות עם יחידות GPU מצורפות לא עוברות מיגרציה פעילה, אלא נעצרות ואפשר להפעיל אותן מחדש. מידע נוסף זמין במאמר טיפול באירועי תחזוקה של מארח GPU.

שליחת שאילתה למפתח המטא-נתונים של אירוע התחזוקה

מכונות וירטואליות של Linux

כדי לשלוח שאילתה למפתח המטא-נתונים maintenance-event במכונות וירטואליות של Linux, מריצים את הפקודה הבאה:

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

כדי לשלוח שאילתה למפתח המטא-נתונים maintenance-event במכונות וירטואליות של Windows, מריצים את הפקודה הבאה:

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.

  • במכונות וירטואליות עם מעבדים גרפיים מצורפים, במכונות Bare Metal או במכונות אחרות שלא תומכות במיגרציה פעילה, הערך של אירוע התחזוקה משתנה מ-NONE ל-TERMINATE_ON_HOST_MAINTENANCE. הערך הזה מתעדכן 60 דקות לפני תחילת אירוע העצירה.

  • במכונות וירטואליות ללא GPU עם אפשרות תזמון של migrate, הערך של maintenance-event משתנה באופן הבא:

    1. בתחילת אירוע ההעברה, הערך משתנה מ-NONE ל-MIGRATE_ON_HOST_MAINTENANCE. הערך הזה מתעדכן 60 שניות לפני שאירוע העצירה מתחיל.
    2. במהלך האירוע ובזמן שהעברת ה-VM מתבצעת בזמן אמת, הערך נשאר MIGRATE_ON_HOST_MAINTENANCE.
    3. אחרי שאירוע התחזוקה מסתיים, הערך חוזר ל-NONE.

  • במכונות וירטואליות עם דייר יחיד, במהלך אירוע תחזוקה של המארח, ערך מפתח המטא-נתונים 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.

המאמרים הבאים