Monitor and plan for a host maintenance event

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 C3 VMs
  • General-purpose C3D 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

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. 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

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.

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://metada.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 and maintenanceStatus=Pending you can trigger the maintenance on the VM.
  • If canReschedule=No and maintenanceStatus=Ongoing the maintenance is already underway.
  • If canReschedule=No and maintenanceStatus=Pending your VM doesn't support manually-triggered maintenance.

What's next