This page describes how to test the effects of your Compute Engineinstance'shost maintenance policyon your applications.

You might simulate a maintenance event on your VMs to test the following:

• The effects oflive migrationon your applications.
• How your applications and batch jobs handle preemption and shutdownwhen using one or moreSpot VMs.
• How your applications handle the shutdown and restart process for instancesthat are configured toterminate and restartduring maintenance events rather than live migrate.
• How workloads that are running onsole-tenant nodesbehave during a host maintenance event, and see the effects of thesole-tenant VM'shost maintenance policyon the applications running on the VMs.

If you try to simulate a host maintenance event on an instance thatdoesn't support live migration,the instance is either terminated or restarted, depending on the configuredhost maintenance policy.

Before you begin

• Review theregional API rate limitforSimulateMaintenanceEventRequestsPerMinutePerProjectPerRegion.
• 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.

Limitations

• To correctly simulate a maintenance event on a sole-tenant node group that hasa host maintenance policy set tomigrate within node group,you need to trigger the maintenance event sequentially on each node.
• For a sole-tenant node group, when you try to simulate a host maintenanceevent and the node group has a host maintenance policy set to migrate withinthe node group:
  • If the number of nodes specified is less than or equal to the total numberof holdback nodes that are reserved, then the host maintenance eventsimulation runs for all the specified nodes simultaneously.
  • If the number of nodes specified is greater than the total number ofreserved holdback nodes, then the simulation fails.
• The number of maintenance event simulations you can start per minute perregion is limited by theAPI rate limit for thesimulate_maintenance_event_requests_per_region metric.

Simulate host maintenance events to test live migration

You can simulate a maintenance event for a compute instance by using either theGoogle Cloud CLI or an API request. This simulated event includes thedifferent maintenance activities that occur in a regular maintenance event. Thislets you observe the end-to-end process and test any automation that youmight have implemented.

During the simulation of host maintenance event for an instance that uses livemigration, themaintenance-event metadata key of the instance goes throughthe following changes:

1. At the start of the simulation, the value of themaintenance-eventmetadata key changes fromNONE toMIGRATE_ON_HOST_MAINTENANCE.
2. Throughout the duration of the simulation event, the value remains asMIGRATE_ON_HOST_MAINTENANCE.
3. After the simulation ends, the value returns toNONE.

To query the maintenance event key, seeQuery the maintenance event metadata key.

gcloud compute instances simulate-maintenance-eventINSTANCE_NAME \    --zone=ZONE --with-extended-notifications=True

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/simulateMaintenanceEvent

Simulate host maintenance for compute instances that terminate

You can simulate a maintenance event for a compute instance by using either theGoogle Cloud CLI or an API request. This simulated event includes thedifferent maintenance activities that occur in a regular maintenance event. Thislets you observe the end-to-end process and test any automation that youmight have implemented.

Additionally, by using the parameter--with-extended-notifications with asupported machine typeyou can test manually starting host maintenance during the simulated event.

Simulate host maintenance events on sole-tenant nodes

You can simulate a host maintenance event on sole-tenant nodes using either theGoogle Cloud CLI or an API request. During the simulation of the hostmaintenance event on a sole-tenant VM, themaintenance-event metadata keyvalue doesn't change and remainsNONE throughout the simulation.

 gcloud compute sole-tenancy node-groups simulate-maintenance-eventNODE_GROUP \    --nodes=NODE_NAMES \    --zone=ZONE \    --async

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/nodeGroups/NODE_GROUP/simulateMaintenanceEvent{  "nodes": [      "NODE_NAMES"  ]}

What's next

• Learn more abouthost events.
• Learn more abouthost maintenance on sole-tenant nodes.
• Learn more aboutsetting VM host maintenance policy options.
• Learn how toview VM operations.
• Learn more aboutmulti- and sole-tenancy.