This page explains how to trigger a host maintenance event on specific VM family instances. This feature lets you manually start a maintenance event to control the timing of your VM's maintenance. This is useful for workloads that might be impacted by a specific maintenance window.
You can manually trigger a maintenance event to start immediately. It is not possible to trigger an event at a specific date or time. If you don't use this feature, the maintenance event occurs as scheduled.
Limitations
Triggering a VM host maintenance event is limited to the following VM machine types:
- Whole host C4 standard, high-mem, and high-cpu machines with 192 vCPUs
- Whole host C3 standard, high-mem, and high-cpu machines with 176 vCPUs
- Whole host H3 VMs with 88 vCPUs
- C3 VMs with Local SSD
- Whole host C3D standard, high-mem, and high-cpu machines with 360 vCPUs
- C3D VMs with Local SSD
- Z3 highmem machines with 176 vCPUs
If you are using VMs from other machine families review the Set host maintenance policy document.
Before you begin
-
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.
Select the tab for how you plan to use the samples on this page:
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
Required roles
To get the permissions that you need to create VMs and manage VM maintenance,
ask your administrator to grant you the
Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1
) IAM role on the project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
This predefined role contains the permissions required to create VMs and manage VM maintenance. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create VMs and manage VM maintenance:
-
To get information about a VM:
compute.instances.get
-
To create a VM:
compute.instances.create
You might also be able to get these permissions with custom roles or other predefined roles.
Trigger host maintenance event
Google sends notifications for upcoming VM maintenance by multiple methods. You can find your notifications by querying your VMs, the metadata server, or Cloud Logging.
After you receive a notification about a host maintenance event, you have the option to trigger the maintenance right away, or wait for the maintenance event to take place as scheduled.
Start the maintenance event
You can start VM maintenance immediately, rather than wait for the scheduled time. Use the Google Cloud CLI or REST method to trigger VM maintenance immediately.
If there is no notification, and you try to trigger a maintenance event, the following message is displayed:
There is no reschedulable upcoming maintenance.
This indicates that no maintenance event has been scheduled and that no action needs to be taken.
gcloud
To start maintenance immediately, use the
gcloud compute instances perform-maintenance
command. You must include the --zone=[ZONE_NAME]
.
gcloud compute instances perform-maintenance VM_NAME \ --zone=ZONE
Replace the following:
VM_NAME
: The of the name of the VM.ZONE
: The zone where the VM resides.
The response looks like this:
upcomingMaintenance:{
"canReschedule":false
"latestWindowStartTime": "2023-12-01T19:00:01Z"
"maintenanceStatus":"ONGOING"
"type":"SCHEDULED"
"windowEndTime": "2023-12-01T22:00:00Z"
"windowStartTime": "2023-12-01T19:00:00Z"
}
In the response, maintenanceStatus
is set to ONGOING
. Maintenance is
underway.
REST
To trigger VM maintenance, run the
instances.performMaintenance
command:
POST: https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/VM_NAME/performMaintenance
Replace the following:
PROJECT_NAME
: The name of the project.ZONE
: The zone where the VM resides.VM_NAME
: The name of the VM.
The response looks like this:
upcomingMaintenance:{
"canReschedule":false
"latestWindowStartTime": "2023-12-01T19:00:01Z"
"maintenanceStatus":"ONGOING"
"type":"SCHEDULED"
"windowEndTime": "2023-12-01T22:00:00Z"
"windowStartTime": "2023-12-01T19:00:00Z"
}
In the response, maintenanceStatus
is set to ONGOING
. Maintenance is
underway.
Maintenance status definitions
The following status definitions explain the responses to a VM maintenance query. They provide information related to VM maintenance. Google Cloud CLI, REST, and the metadata server use these same responses:
- windowStartTime: the start of the time window in which maintenance occurs
- windowEndTime: the end of the time window in which maintenance occurs
- latestWindowStartTime: the earliest time the window can be moved to
- maintenanceType: the type of maintenance to be performed
- NONE: no maintenance is scheduled for this VM
- SCHEDULED: maintenance will get 7 days' notice
- UNSCHEDULED: maintenance represents critical updates for which much less notice is given
- canReschedule: whether the maintenance can be triggered during the
notification period for this VM
- TRUE: customer-triggered maintenance can be performed during the notification period
- FALSE: customer-triggered maintenance can't be performed on this VM This often occurs during the period in which the VM is undergoing maintenance
- maintenanceStatus: the current maintenance operation's status
- ONGOING: the maintenance operation is underway
- PENDING: the maintenance operation is scheduled, but has not yet started
Maintenance status behaviors
While you are managing the maintenance schedule, check the status of
canReschedule=
and maintenanceStatus=
these response combinations describe
the features expected behavior and display one of the following status
combinations:
- If
canReschedule=Yes
andmaintenanceStatus=Pending
you can trigger the maintenance on the VM. - If
canReschedule=No
andmaintenanceStatus=Ongoing
the maintenance is already underway. - If
canReschedule=No
andmaintenanceStatus=Pending
your VM doesn't support manually-triggered maintenance.
What's next
- Learn how to Simulate a host maintenance event.
- Learn how to Get live migration notices.
- Learn how to create a log-based alert in Cloud Logging.