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

You can manually start a host maintenance event for instances that use the following machine types:

• Accelerator-optimized machine families:

  • A3 Mega machine types with 8 GPUs

  • A3 High machine types with 8 GPUs

  • A3 Edge machine types with 8 GPUs

  • A2 Ultra machine types with 8 GPUs

  • A2 Standard machine types with 8 or 16 GPUs

  • G2 machine types with 8 GPUs

• Compute-optimized machine families:

  • H3 machine types with 88 vCPUS

• General purpose machine families:

  • C4 machine types with 192 vCPUS

  • C3D machine types with 360 vCPUs or with Local SSD disks attached

  • C3 machine types with 176 vCPUS or with Local SSD disks attached

  • C3 bare metal instances with 192 vCPUS

• Memory-optimized machine families:

  • X4 machine types

  • M3 machine types

  • M2 machine types

  • M1 machine types

• Storage-optimized machine families:

  • Z3 machine types with 176 vCPUs

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:

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:

• Querying your compute instances or metadata server
• Using Cloud Logging

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 compute instances perform-maintenance INSTANCE_NAME \
    --zone=ZONE

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

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

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

What's next

• Learn how to Simulate a host maintenance event.
• Learn how to Get live migration notices.
• Learn how to Configure alerts for host maintenance notifications.