Membuat kueri server metadata untuk mendapatkan pemberitahuan peristiwa pemeliharaan

Server metadata memberikan informasi tentang opsi dan setelan penjadwalan instance Compute Engine, melalui listingan direktori metadata scheduling/ dan kunci metadata maintenance-event. Anda dapat menggunakan kunci metadata ini untuk mempelajari opsi penjadwalan VM, dan juga untuk memberi tahu Anda tentang peristiwa pemeliharaan mendatang.

Server metadata menerima notifikasi peristiwa pemeliharaan sebelum instance komputasi dimigrasikan langsung atau dihentikan. Untuk mempelajari lebih lanjut peristiwa pemeliharaan dan perilaku instance selama peristiwa terjadi, lihat Ringkasan pemeliharaan host.

Untuk kumpulan VM tertentu, opsi pemeliharaan VM Anda lebih fleksibel. Untuk mempelajari lebih lanjut, lihat Memantau dan merencanakan peristiwa pemeliharaan host.

Sebelum memulai

  • Untuk VM Windows Server, gunakan PowerShell 3.0 atau yang lebih baru. Sebaiknya gunakan ctrl+v untuk menempelkan blok kode yang disalin.
  • Jika Anda belum melakukannya, siapkan autentikasi. Autentikasi adalah proses verifikasi identitas Anda untuk mengakses layanan dan API Google Cloud. Untuk menjalankan kode atau contoh dari lingkungan pengembangan lokal, Anda dapat mengautentikasi ke Compute Engine dengan memilih salah satu opsi berikut:

    Untuk menggunakan contoh Python di halaman ini dalam lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. 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.

    Untuk informasi selengkapnya, lihat Set up authentication for a local development environment.

Mendapatkan pemberitahuan migrasi langsung

Anda dapat mempelajari kapan migrasi langsung akan terjadi untuk instance Anda dengan membuat kueri kunci metadata maintenance-event secara berkala.

Kunci metadata maintenance-event diisi untuk peristiwa pemeliharaan hanya jika Anda telah menetapkan opsi penjadwalan VM ke migrate atau jika VM Anda memiliki GPU yang terpasang.

Nilai kunci metadata ini berubah 60 detik sebelum peristiwa pemeliharaan dimulai, sehingga memberi kode aplikasi Anda cara untuk memicu tugas apa pun yang ingin dilakukan sebelum peristiwa pemeliharaan, seperti mencadangkan data atau mengupdate log.

Compute Engine memberikan peringatan 60 detik hanya jika:

  • Anda telah menetapkan opsi ketersediaan VM untuk migrasi langsung selama peristiwa pemeliharaan.

  • Anda telah membuat kueri kunci metadata maintenance-event setidaknya sekali sejak peristiwa pemeliharaan terakhir.

    • Jika Anda belum pernah membuat kueri kunci metadata maintenance-event atau belum membuat kueri kunci metadata sejak migrasi terakhir, Compute Engine akan menganggap bahwa VM tidak memerlukan peringatan awal tentang peristiwa pemeliharaan. Peristiwa pemeliharaan segera dimulai dan melewati peringatan 60 detik.

    • Jika tidak ingin melewati peringatan 60 detik, pastikan kode klien Anda membuat kueri kunci metadata maintenance-event setidaknya sekali di antara peristiwa migrasi. Anda harus membuat kueri kunci metadata maintenance-event secara langsung untuk Compute Engine agar dapat menentukan bahwa Anda memantau kunci metadata ini. Membuat kueri untuk metadata dengan level yang lebih tinggi tidak memicu pemberitahuan awal.

Untuk VM dengan GPU yang terpasang, nilainya akan berubah 60 menit sebelum VM dihentikan guna memberi Anda waktu untuk mematikan dan memulai ulang lagi di host lain. VM dengan GPU yang terpasang tidak dimigrasikan langsung, melainkan dihentikan dan dimulai ulang secara opsional. Untuk mempelajari lebih lanjut, lihat Menangani peristiwa pemeliharaan host GPU.

Membuat kueri kunci metadata aktivitas pemeliharaan

VM Linux

Untuk membuat kueri kunci metadata maintenance-event di VM Linux, jalankan perintah berikut:

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

Outputnya mirip dengan hal berikut ini:

NONE

Anda juga dapat menggunakan opsi wait-for-change. Dengan menentukan opsi ini, permintaan hanya menampilkan output saat peristiwa pemeliharaan akan dimulai dan berakhir.

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

VM Windows

Untuk membuat kueri kunci metadata maintenance-event di VM Windows, jalankan perintah berikut:

PS C:\> 
$value = (Invoke-RestMethod `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event")
$value

Outputnya mirip dengan hal berikut ini:

NONE

Anda juga dapat menggunakan opsi wait-for-change. Dengan menentukan opsi ini, permintaan hanya menampilkan output saat acara pemeliharaan akan dimulai dan berakhir.

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

Anda dapat menggunakan kunci metadata maintenance-event dengan fitur menunggu update untuk memberi tahu skrip dan aplikasi saat peristiwa pemeliharaan akan dimulai dan berakhir. Hal ini memungkinkan Anda mengotomatiskan tindakan apa pun yang mungkin ingin dijalankan sebelum atau setelah peristiwa tersebut.

Contoh Python berikut memberikan contoh cara menerapkan kedua fitur ini secara bersamaan.


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()

Meninjau output

Nilai awal dan default kunci metadata maintenance-event adalah NONE.

  • Untuk VM dengan GPU yang terpasang, instance bare metal, atau instance lain yang tidak mendukung migrasi langsung, nilai peristiwa pemeliharaan akan berubah dari NONE menjadi TERMINATE_ON_HOST_MAINTENANCE. Nilai ini diperbarui 60 menit sebelum peristiwa penghentian dimulai.

  • Untuk VM non-GPU dengan opsi penjadwalan migrate, nilai maintenance-event akan berubah sebagai berikut:

    1. Pada awal peristiwa migrasi, nilai akan berubah dari NONE menjadi MIGRATE_ON_HOST_MAINTENANCE. Nilai ini diperbarui 60 detik sebelum peristiwa penghentian dimulai.
    2. Selama peristiwa berlangsung dan saat instance VM Anda sedang dimigrasikan langsung, nilainya akan tetap sebagai MIGRATE_ON_HOST_MAINTENANCE.
    3. Setelah peristiwa pemeliharaan berakhir, nilai akan ditampilkan menjadi NONE.

  • Untuk VM tenant tunggal, selama peristiwa pemeliharaan host, nilai kunci metadata maintenance-event tidak berubah dan tetap NONE dari awal hingga akhir peristiwa.

Untuk seri mesin yang mendukung kemampuan pemeliharaan lanjutan, sebelum peristiwa pemeliharaan, Anda dapat membuat kueri kunci metadata upcoming-maintenance. Jika ada notifikasi yang tersedia untuk instance Anda, Anda akan melihat nilai yang mirip dengan berikut:

{
   "maintenanceType":"SCHEDULED"
   "canReschedule": "true"
   "latestWindowStartTime": "2025-08-28T21:56:21Z"
   "maintenanceStatus": "PENDING"
   "windowEndTime": "2025-08-29T01:56:20Z"
   "windowStartTime": "2025-08-28T21:56:26Z"
}

Kunci metadata upcoming-maintenance diisi sebelum peristiwa pemeliharaan sebagai berikut:

  • C3: hingga 7 hari
  • C3D: hingga 7 hari
  • X4: hingga 60 hari
  • Z3: hingga 7 hari

Langkah berikutnya