Linux
Windows
The metadata server provides information about a virtual machine (VM) instance's
scheduling options and settings,
through the
scheduling/
metadata directory listing and the
maintenance-event
metadata key. You can use these metadata keys to learn about a VM's scheduling
options, and also for notifying you when a maintenance event is about to happen.
By default, all VMs (except Z3) are set to
live migrate
and
the metadata server receives maintenance event notices before a VM instance
is live migrated. However, if you choose a different scheduling option the
maintenance events and the VM behavior might differ. To learn more about
maintenance events and VM behavior during the events, see
Host maintenance overview
.
Before you begin
- For Windows Server VMs, use
PowerShell 3.0 or later
.
We recommend that you use
ctrl+v
to paste the copied code blocks.
-
If you haven't already, set up authentication.
Authentication
is
the process by which your identity is verified for access to Google Cloud services and APIs.
To run code or samples from a local development environment, you can authenticate to
Compute Engine as follows.
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.
-
To
initialize
the gcloud CLI, run the following command:
gcloud init
-
Create local authentication credentials for your Google Account:
gcloud auth application-default login
For more information, see
Set up authentication for a local development environment
.
Get live migration notices
You can learn when a maintenance event will occur by querying the
maintenance-event
metadata key periodically.
The
maintenance-event
metadata key is populated for
maintenance events only if you have set your VM's scheduling option to
migrate
or if your VM has a GPU attached.
The value of this metadata key changes 60 seconds before a maintenance event
starts, giving your application code a way to trigger any tasks you want to
perform prior to a maintenance event, such as backing up data or updating logs.
In summary, Compute Engine gives the 60-second warning only if:
For VMs with attached GPUs, the value changes 60 minutes before the
VMs are stopped to give you time to shutdown and restart again on
another host. VMs with attached GPUs are not live migrated and are instead
stopped and optionally restarted. To learn more, see
Handling GPU host maintenance events
.
For a specific set of VMs, your VM maintenance options are more flexible. To
learn more, see
Monitor and plan for a host maintenance event
.
Query the maintenance event metadata key
Linux VMs
To query the
maintenance-event
metadata key on Linux VMs, run the following command:
user@myinst:~$
curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"
The output is similar to the following:
NONE
Windows VMs
To query the
maintenance-event
metadata key on Windows VMs, run the following command:
PS C:\>
$value = (Invoke-RestMethod `
-Headers @{'Metadata-Flavor' = 'Google'} `
-Uri "http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event")
$value
The output is similar to the following:
NONE
Python
You can use the
maintenance-event
metadata key with the
waiting for updates
feature to notify your scripts and applications when a maintenance event is
about to start and end. This lets you automate any actions that you might
want to run before or after the event.
The following Python sample provides an example of how you might implement
these two features together.
Review the outputs
The initial and default value of the
maintenance-event
metadata key is
NONE
.
For VMs with attached GPUs, during a
maintenance event
the value
changes from
NONE
to
TERMINATE_ON_HOST_MAINTENANCE
. This
value is updated 60 minutes before the stopping event starts.
For non-GPU VMs with a scheduling option of
migrate
, the
maintenance-event
value changes as follows:
- At the start of the migration event, the value changes from
NONE
to
MIGRATE_ON_HOST_MAINTENANCE
. This value is updated 60 seconds before
the stopping event starts.
- Throughout the duration of the event and while your VM instance is being
live migrated, the value remains as
MIGRATE_ON_HOST_MAINTENANCE
.
- After the maintenance event ends, the value returns to
NONE
.
For sole-tenant VMs, during a host maintenance event, the
maintenance-event
metadata key value doesn't change and remains
NONE
from the start to
the end of the event.
What's next