This document explains how to use the host maintenance features that are availablewith H4D VMs. It explains how to monitor, plan for,and perform scheduled maintenance on virtual machine (VM) instances.To manage maintenance on your reserved blocks of capacity, whether or not VMsare running on them, see insteadManage host events across reservations.

When you proactively manage upcomingmaintenance host events onyour VMs, you can minimize disruptions and maintain optimal performance.

Before you begin

Select the tab for how you plan to use the samples on this page:

Required roles

To get the permissions that you need to manage host maintenance events across VMs, ask your administrator to grant you the following IAM roles:

• Compute Admin (roles/compute.admin) on the project
• For read-only access to System Event audit logs:Logs Viewer (roles/logging.viewer) on the project

For more information about granting roles, seeManage access to projects, folders, and organizations.

These predefined roles contain the permissions required to manage host maintenance events across VMs. 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.

Overview

To optimize the maintenance of your VMs, complete the following steps:

1. Understand host maintenance. Learn about the frequency and maintenancebehavior of your VMs based on their machine series. This information helpsyou minimize disruptions to your workloads.

2. Set up notification alerts. Create log-based alerts to receivenotifications when maintenance for your VMs is scheduled, started, orcompleted. This approach helps you proactively plan your activities andavoid unexpected downtime.

3. Manage maintenance across VMs. View if maintenance is scheduled for yourVMs. If needed, you can manually start maintenance across your VMs. Thisprocess helps you increase the resilience of your workloads to host events,prevent downtime, and maximize the availability of your applications.

Understand host maintenance

During thelifecycle of aCompute Engine instance, the host machine that your instance runs on undergoes multiplehost events.A host event can include the regular maintenance ofCompute Engine infrastructure, or in rare cases, a host error. Compute Engine alsoapplies some non-disruptive lightweight upgrades for the hypervisor and networkin the background.

The H4D machine series offers the following features related to hostmaintenance:

The maintenance frequencies shown in the previous table are approximations, not guarantees.Compute Engine might occasionally perform maintenance more frequently.

Set up notification alerts for VMs

You can get notified about scheduled, started, or completed maintenance eventsfor your VMs bycreating log-based alerting policies.

To create an alert for the maintenance events of your VMs, complete thefollowing procedure. Repeat this procedure for each alertthat you want to create.

1. In the Google Cloud console, go to thesegmentLogs Explorer page:

   Go toLogs Explorer

   If you use the search bar to find this page, then select the result whose subheading isLogging.

2. Click theShow query toggle to the on position.

3. In theQuery pane, build one of the following queries. These queriesfilter log entries to identify specific maintenance events. If you want touse multiple queries, repeat this procedure to create an unique alert foreach query.

   • To receive alerts when maintenance for a VM is scheduled:

     protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULTprotoPayload.status.message =~ "scheduled"

   • To receive alerts when the maintenance window for a VM has opened:

     protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULTprotoPayload.status.message =~ "ongoing"

   • To receive alerts when maintenance for a VM has started:

     protoPayload.methodName="compute.instance.terminateOnHostMaintenance" severity>=DEFAULT

   • To receive alerts when maintenance for a VM has completed:

     protoPayload.methodName="compute.instances.upcomingMaintenance" severity>=DEFAULTprotoPayload.status.message =~ "completed"

4. To validate the query, clickRun query. If the query is valid, then theQuery results pane displays log entries that match the query.

5. In theQuery results toolbar, click theActions list, and thenselectadd_alertCreate log alert.TheCreate logs-based alert policy pane appears.

6. In theAlert details section, do the following:

   1. In theAlert Policy Name field, enter a name for the policy.

   2. In thePolicy severity level list, selectWarning (or a higherseverity).

   3. ClickNext.

7. In theChoose logs to include in the alert section, clickNext.

8. In theSet notification frequency and autoclose duration section,specify the following:

   1. In theTime between notifications list, select how often you want tobe notified.

   2. In theIncident autoclose duration list, select after how longCloud Logging stops sending notifications and automatically closesthe incident.

   3. ClickNext.

9. In theWho should be notified? section, specify anotification channel forLogging to send notifications to.

10. ClickSave.

To view examples of maintenance event notifications in the Logs Explorer,seeExamples of maintenance notificationsin the Compute Engine documentation.

Manage maintenance across VMs

You can view and control maintenance for your VMs by doing one or more of thefollowing:

• To check the state and scheduled time of upcoming maintenance for your VMs,view the maintenance state of VMs.

• To immediately start maintenance on your VMs, rather than waiting for theirscheduled maintenance time,manually start maintenance on VMs.

View the maintenance state of VMs

You can view the state and scheduled time of upcoming maintenance for your VMsby checking the value of theupcomingMaintenance field in the instance'smetadata. If a VM doesn't contain theupcomingMaintenance field, then no hostmaintenance event is scheduled for the VM. For more information about the fieldsinupcomingMaintenance, seeMaintenance status definitionsin the Compute Engine documentation.

Additionally, if maintenance is scheduled for an VM, theupcomingGroupMaintenance field contains themaintenanceReasons field. Thisfield describes why maintenance was scheduled for your VM, as described in thefollowing table:

To view themaintenanceReasons field in a VM, you must use thegcloud CLI or REST API. To view the maintenance state formultiple VMs simultaneously, you must use the Google Cloud console or RESTAPI. Otherwise, select one of the following options:

gcloud compute instances describeVM_NAME \    --flatten=resourceStatus.upcomingMaintenance \    --zone=ZONE

{  "items": [    {      "name": "vm-01",      "machineType": "https://www.googleapis.com/compute/v1/projects/example-project/zones/europe-west4-b/machineTypes/h4d-highmem-192-lssd",      "resourceStatus": {        "upcomingMaintenance": {          "canReschedule": true,          "latestWindowStartTime": "2024-11-01T19:00:00Z",          "maintenanceStatus": "PENDING",          "maintenanceReasons": [            "PLANNED_UPDATE",            "PLANNED_NETWORK_UPDATE"          ],          "type": "SCHEDULED",          "windowEndTime": "2024-11-01T22:00:00Z",          "windowStartTime": "2024-11-01T19:00:00Z"        }      }    },    ...  ]}

Manually start maintenance on VMs

You can manually start maintenance for your VMs instead of waiting for thescheduled time.

Depending on the maintenance state of a VM, the following occurs:

You can manually start maintenance for multiple VMs simultaneously or forindividual VMs. For multiple VMs, use the Google Cloud console or, for VMslocated in the same zone, the gcloud CLI. For individual VMs, selectany of the following options:

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

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/performMaintenance