Manually start a host maintenance event

This page explains how to manually start a host maintenance event on supported Compute Engine instances. This feature lets you start a maintenance event to control the timing of your instance's maintenance. This is useful for workloads that might be impacted by degraded performance or downtime, for which you need the maintenance window to start at a specific time.

When you manually start a maintenance event, the host maintenance starts immediately. You can't specify a date or time for the maintenance event to start. If you don't use this feature, then the maintenance event occurs at the time indicated in the upcoming maintenance notification.

If you want to first test how your applications will handle a maintenance event, you can simulate a maintenance event.

Limitations

Manually starting a host maintenance event for an instance is limited to the following machine types:

Before you begin

  • If you haven't already, then 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 by selecting one of the following options:

    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

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to 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 manage VM maintenance. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage VM maintenance:

  • To get information about a compute instance: compute.instances.get
  • To start host maintenance for an instance: compute.instances.performMaintenance

You might also be able to get these permissions with custom roles or other predefined roles.

Manually start a host maintenance event

Compute Engine sends notifications for upcoming maintenance events by multiple methods. Using the information in the notifications, you can determine the timeframe for when you can manually start a maintenance event.

Check the notification information

You can find your maintenance event notifications by:

If the notification about a host maintenance event contains canReschedule=True and maintenanceStatus=Pending, then you have the option to start the maintenance at a time of your choosing, or wait for the maintenance event to take place at the time specified by windowStartTime.

If there is no notification, and you try to manually start 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.

Start the maintenance event

You can start host maintenance at a time of your choosing, rather than wait for the scheduled time. Use the Google Cloud CLI or REST to trigger the maintenance event, which then starts immediately.

gcloud

To start a maintenance event, use the compute instances perform-maintenance command. The host maintenance starts immediately after entering the command.

gcloud compute instances perform-maintenance INSTANCE_NAME \
    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: The of the name of the compute instance.
  • ZONE: The zone where the instance resides.

The response is similar to the following:

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, canReschedule is set to false and maintenanceStatus is set to ONGOING, which indicates that the host maintenance operation is underway.

REST

To start a maintenance event, construct a POST request using the instances.performMaintenance method.

POST: https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/INSTANCE_NAME/performMaintenance

Replace the following:

  • PROJECT_NAME: The name of the project
  • ZONE: The zone where the compute instance resides
  • INSTANCE_NAME: The name of the instance

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, canReschedule is set to false and maintenanceStatus is set to ONGOING, which indicates that the host maintenance operation is underway.

What's next