This page explains how to manually start ahost maintenance event onsupported Compute Engine instances. This feature letsyou start a maintenance event to control the timing of your instance'smaintenance. This is useful for workloads that might be impacted by degradedperformance or downtime, for which you need the maintenance window to startat a specific time.

When you manually start a maintenance event, the host maintenance startsimmediately. You can't specify a date or time for the maintenanceevent to start. If you don't use this feature, then the maintenance eventoccurs at the time indicated in theupcoming maintenance notification.

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

Limitations

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

• Accelerator-optimized machine families:

  • A4X machine types with 4 GPUs

  • A4 machine types with 8 GPUs

  • A3 Ultra machine types with 8 GPUs

  • 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

  • G4 machine types with 8 GPUs

  • G2 machine types with 8 GPUs

• Compute-optimized machine families:

  • H3 machine types with 88 vCPUs

  • H4D machine types with 192 vCPUs

• General-purpose machine families:

  • C4 machine types with 192 or 288 vCPUs or with Local SSD disks attached

  • C4 bare metal instances with 288 vCPUs

  • C4A machine types with Local SSD disks attached

  • C4D machine types with 384 vCPUs or with Local SSD disks attached

  • C4D bare metal instances with 384 vCPUs

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

  • C3 bare metal instances with 192 vCPUs

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

• Memory-optimized machine families:

  • X4 machine types

  • M4 machine types

  • M3 machine types

  • M2 machine types

  • M1 machine types

• Storage-optimized machine families:

  • Z3 machine types

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity 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. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  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. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate 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 theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the project. For more information about granting roles, seeManage 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 theRequired permissions section:

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Manually start a host maintenance event

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

Check the notification information

You can find your maintenance event notifications in one of the following ways:

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

If the notification about a host maintenance event containscanReschedule=TrueandmaintenanceStatus=Pending, then you have the option to start themaintenance at a time of your choosing, or wait for the maintenance event totake place at the time specified bywindowStartTime.

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 message indicates that no maintenance event has been scheduled and that noaction needs to be taken.

Start the maintenance event

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

gcloud compute instances perform-maintenanceINSTANCE_NAME \    --zone=ZONE

resourceStatus:  upcomingMaintenance:    canReschedule: false    latestWindowStartTime: '2025-01-15T19:57:17Z'    maintenanceStatus: ONGOING    type: SCHEDULED    windowEndTime: '2025-01-15T23:57:11Z'    windowStartTime: '2025-01-15T19:57:16Z'

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 toSimulate a host maintenance event.
• Learn how toGet live migration notices.
• Learn how toConfigure alerts for host maintenance notifications.