Maintenance on all virtual machine (VM) instances is determined by the host maintenance policy you select when you create your VMs. Some VMs offer the additional option of viewing the VM's maintenance schedule ahead of time.
This page explains how to monitor and plan for a host maintenance event on Compute Engine VMs. To view the maintenance schedule for a VM, the VM must be running a machine type from one of the following machine families:
- General-purpose C4 VMs
- General-purpose C3 VMs
- General-purpose C3D VMs
- Compute-optimized H3 VMs
- Storage-optimized Z3 VMs
- Memory-optimized M1, M2, M3 VMs
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:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
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.
Monitor maintenance notifications
Google sends notifications for upcoming VM maintenance through several methods. You can find your notifications by querying your VMs, the metadata server, or Cloud Logging. When the scheduled maintenance window opens, Google Cloud automatically performs maintenance on your VM. By monitoring your VM's scheduled maintenance windows, you can proactively prepare your workloads to handle upcoming maintenance with minimal disruption.
VMs with maintenance event notifications have the following characteristics:
- Fewer maintenance events: In general, VMs with recurrent maintenance intervals should see fewer maintenance events.
- Longer maintenance notification: Get notified of planned maintenance events well in advance for planning purposes.
- Monitoring and planning: Use Cloud Logging to track your maintenance schedule. Use incidents and alerts to stay informed.
On-demand maintenance control: Start maintenance during the notification period to update your VMs when it fits your schedule.
Check VMs for a maintenance event notification
Use the Google Cloud CLI, REST method, or metadata server to see if there is an upcoming VM maintenance event.
gcloud
To see the upcoming maintenance window for a VM, use the
gcloud compute instances describe
command. You must include the --zone=[ZONE_NAME]
.
gcloud compute instances describe VM_NAME \ --zone=ZONE
Replace the following:
VM_NAME
: The name of the VM.ZONE
: The zone where the VM resides.
The response looks like this:
upcomingMaintenance:{
"canReschedule":True
"latestWindowStartTime": "2023-12-01T19:00:01Z"
"maintenanceStatus":"PENDING"
"type":"SCHEDULED"
"windowEndTime": "2023-12-01T22:00:00Z"
"windowStartTime": "2023-12-01T19:00:00Z"
}
In this response, canReschedule
is set to True
and the maintenanceStatus
is set to PENDING
. The maintenance is scheduled for the displayed date
and time. These settings indicate you can manually trigger this event ahead
of time.
REST
To see if there is upcoming maintenance for a VM, run the
instances.get
command:
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/VM_NAME
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":True
"latestWindowStartTime": "2023-12-01T19:00:01Z"
"maintenanceStatus":"PENDING"
"type":"SCHEDULED"
"windowEndTime": "2023-12-01T22:00:00Z"
"windowStartTime": "2023-12-01T19:00:00Z"
}
In this response, canReschedule
is set to TRUE
and the maintenanceStatus
is set to PENDING
. The maintenance is scheduled for the displayed date
and time.
metadata server
From the Guest OS, query the metadata server to see the next maintenance event.
$ curl http://metadata.google.internal/computeMetadata/v1/instance/upcoming-maintenance?alt=json -H "Metadata-Flavor: Google"
Check Cloud Logging for a maintenance event notification
Google sends a notification to Cloud Logging prior to VM
maintenance. Cloud Logging generates a system event in the Logs Explorer.
The VM's scheduled maintenance appears in Cloud Logging
as: compute.instances.upcomingMaintenance
.
Depending on your VM configuration, Cloud Logging displays the event in the following manner:
- For VMs configured to use live migration for maintenance, the event displays
with the method name:
compute.instances.migrateOnHostMaintenance
. - For VMs configured to use Terminate and Automatic Restart for maintenance, the
event displays with the method name:
compute.instances.terminateOnHostMaintenance
.
If your VM is configured to use live migration, after the maintenance is
completed compute.instances.upcomingMaintenance
appears, indicating that the
notification is cleared.
You might benefit from setting up alerts to receive maintenance notifications. To learn more, read Configure log-based alerts and Create and manage notification channels.
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 Set a VM host maintenance policy.
- Learn how to Get live migration notices.
- Learn how to manually Trigger a host maintenance event
- Learn how to create a log-based alert in Cloud Logging.