Trigger a host maintenance event

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:

Before you begin

  • Manually starting VM maintenance is only available on C3, C3D, and Z3 VMs. If you are using VMs from other machine families review the Set host maintenance policy document.

  • 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

    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.

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 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