The metadata server provides information about a Compute Engine instance'sscheduling options and settings,through thescheduling/ metadata directory listing and themaintenance-eventmetadata key. You can use these metadata keys to learn about a VM's schedulingoptions, and also to notify you of an upcoming maintenance event.

The metadata server receives maintenance event notices before a compute instanceis live migrated or terminated. To learn more about maintenance events andinstance behavior during the events, seeHost maintenance overview.

For a specific set of VMs, your VM maintenance options are more flexible. Tolearn more, seeMonitor and plan for a host maintenance event.

Before you begin

• For Windows Server VMs, usePowerShell 3.0 or later. We recommend that you usectrl+v to paste the copied code blocks.
• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  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.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloudauthapplication-defaultlogin

  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.

Get live migration notices

You can learn when live migration is about to happen for your instanceby querying themaintenance-event metadata key periodically.

Themaintenance-event metadata key is populated formaintenance events only if you have set your VM's scheduling option tomigrate or if your VM has a GPU attached.

The value of this metadata key changes 60 seconds before a maintenance eventstarts, giving your application code a way to trigger any tasks you want toperform prior to a maintenance event, such as backing up data or updating logs.

Compute Engine gives the 60-second warning only if:

• You have set the VM'savailability optionsto live migrate during a maintenance event.

• You have queried themaintenance-event metadata key at least once since thelast maintenance event.

  • If you have never queried themaintenance-eventmetadata key or have not queried the metadata key since the last migration,Compute Engine assumes that the VM doesn't require advancewarning of maintenance events. The maintenance event initiates immediatelyand skips the 60-second warning.

  • If you don't want to skip the 60-second warning, make sure your client codequeries themaintenance-event metadata key at least once between migrationevents. You must query themaintenance-event metadata key directly forCompute Engine to determine that you are watching this metadata key.Querying a higher level metadata doesn't trigger the advance notice.

For VMs with attached GPUs, the value changes 60 minutes before theVMs are stopped to give you time to shutdown and restart again onanother host. VMs with attached GPUs are not live migrated and are insteadstopped and optionally restarted. To learn more, seeHandling GPU host maintenance events.

Query the maintenance event metadata key

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

importtimefromtypingimportCallable,NoReturn,OptionalimportrequestsMETADATA_URL="http://metadata.google.internal/computeMetadata/v1/"METADATA_HEADERS={"Metadata-Flavor":"Google"}defwait_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=Nonelast_etag="0"whileTrue: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.ifr.status_code==503:time.sleep(1)continuer.raise_for_status()last_etag=r.headers["etag"]ifr.text=="NONE":maintenance_event=Noneelse:maintenance_event=r.textifmaintenance_event!=last_maintenance_event:last_maintenance_event=maintenance_eventcallback(maintenance_event)defmaintenance_callback(event:Optional[str])->None:"""Example callback function to handle the maintenance event.    Args:        event: details about scheduled maintenance.    """ifevent:print(f"Undergoing host maintenance:{event}")else:print("Finished host maintenance")defmain():wait_for_maintenance(maintenance_callback)if__name__=="__main__":main()

Review the outputs

The initial and default value of themaintenance-event metadata key isNONE.

• For VMs with attached GPUs, bare metal instances, or other instances thatdon't support live migration,maintenance event the valuechanges fromNONE toTERMINATE_ON_HOST_MAINTENANCE. Thisvalue is updated 60 minutes before the stopping event starts.

• For non-GPU VMs with a scheduling option ofmigrate, themaintenance-event value changes as follows:

  1. At the start of the migration event, the value changes fromNONE toMIGRATE_ON_HOST_MAINTENANCE. This value is updated 60 seconds beforethe stopping event starts.
  2. Throughout the duration of the event and while your VM instance is beinglive migrated, the value remains asMIGRATE_ON_HOST_MAINTENANCE.
  3. After the maintenance event ends, the value returns toNONE.

• For sole-tenant VMs, during a host maintenance event, themaintenance-eventmetadata key value doesn't change and remainsNONE from the start tothe end of the event.

For machine series that supportadvanced maintenance capabilities,prior to a maintenance event you can query the metadata keyupcoming-maintenance. If there is a notification available for your instanceyou should see values similar to the following:

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

To determine how long before a maintenance event theupcoming-maintenancemetadata key is populated, see the "Maintenance experience" documentation forthe machine series. For example, for Z3 machine types, seeMaintenance experience for Z3 instances.

• Learn aboutsetting instance availability policies.
• Learn how tosimulate a host maintenance event.
• Learn more aboutlive migration.
• Learn more aboutVM metadata.