Set VM host maintenance policy

Linux Windows

This document describes how you can set a virtual machine (VM) instance's host maintenance policy to configure the behavior of the VM when a host event occurs.

Before you begin

If you want to use the command-line examples in this guide, do the following:
1. Install or update to the latest version of the Google Cloud CLI.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.

Limitations

You can't change the host maintenance policy of a preemptible VM. When there is a maintenance event, the preemptible VM stops and it does not migrate. You must manually restart the preempted VM.
After you create a VM using an E2 machine type, you can't change the VM's host maintenance settings from Migrate to Terminate or the other way around.

Set host maintenance policy of a VM

You can change the host maintenance policy of a VM when you first create a VM or after the VM is created, by using the setScheduling method. To configure a VM's maintenance behavior, restart behavior, and host error detection time, use the onHostMaintenance, automaticRestart, and hostErrorTimeoutSeconds properties. Compute Engine configures all VMs with default values unless you specify otherwise.

onHostMaintenance: determines the behavior when a maintenance event occurs that might cause your VM to reboot.
- MIGRATE: causes Compute Engine to live migrate an instance when there is a maintenance event. This is the default value.
- TERMINATE: stops a VM instead of migrating it.
automaticRestart: determines the behavior when a VM crashes or is stopped by the system.
- true: Compute Engine restarts an instance if the instance crashes or is stopped. This is the default value.
- false: Compute Engine does not restart a VM if the VM crashes or is stopped.
hostErrorTimeoutSeconds (Preview): Sets the maximum amount of time, in seconds, that Compute Engine waits to restart or terminate a VM after detecting that the VM is unresponsive.
- [Default] unset, Compute Engine waits up to 5.5 minutes (330 seconds) before restarting an unresponsive VM.
- Number of seconds between 90 and 330, in increments of 30, which sets how long Compute Engine waits before restarting an unresponsive VM.

All VMs are configured with default values unless you explicitly specify otherwise.

Set host maintenance policy during VM creation

Console

In the Google Cloud console, go to the Create an instance page.

Go to Create an instance
Expand the Networking, disks, security, management, sole tenancy section, and do the following:
1. Expand the Management section.
2. In the Automatic restart list, select the option that you want.
3. In the On host maintenance list, select the option that you want.
To create the VM, click Create.

gcloud

To set the host maintenance policy of a new VM in gcloud compute, use the --maintenance-policy flag to specify whether the VM is migrated or stopped. By default, VMs are automatically set to restart unless you provide the --no-restart-on-failure flag.

To specify the maximum amount of time Compute Engine waits to restart or terminate a VM after detecting that the VM is unresponsive, use the --host-error-timeout-seconds flag (Preview).

gcloud compute instances create VM_NAME \
    --maintenance-policy=MAINTENANCE_POLICY \
    --host-error-timeout-seconds=NUMBER_OF_SECONDS \
    [--no-restart-on-failure]

Replace the following:

VM_NAME: the VM name
MAINTENANCE_POLICY: the policy for this VM, either TERMINATE or MIGRATE
NUMBER_OF_SECONDS: the number of seconds Compute Engine waits before restarting an unresponsive VM, between 90 and 330, in increments of 30. This option is available in Preview. To use this option use the gcloud beta compute instances create command.

API

To set the host maintenance policy of a new VM using the Compute Engine API, use the instances.insert method.

In the request body, add onHostMaintenance to specify whether the VM is migrated or stopped during host maintenance. VMs are automatically set to restart after a host error, unless you set automaticRestart to false.

To specify the maximum amount of time Compute Engine waits to restart or terminate a VM after detecting that the VM is unresponsive, add the hostErrorTimeoutSeconds (Preview) parameter to the request body.

In the API, make a POST request to the following URL, replacing the project and zone with your project ID and the zone of the VM:

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

Replace the following:

PROJECT_ID: the project you want to create the VM in
ZONE: the zone where you want to create the VM

Add the onHostMaintenance, hostErrorTimeoutSeconds, and automaticRestart parameters as part of the request body:

{
 "name": "VM_NAME",
 ...
 // User options for influencing this Instance's life cycle.
 "scheduling": {
   "onHostMaintenance": "MAINTENANCE_POLICY",
   "hostErrorTimeoutSeconds": NUMBER_OF_SECONDS,
   "automaticRestart": RESTART_POLICY
 }
}

Replace the following:

VM_NAME: the VM name
MAINTENANCE_POLICY: the policy for this VM, either TERMINATE or MIGRATE
NUMBER_OF_SECONDS: the number of seconds Compute Engine waits before restarting an unresponsive VM, between 90 and 330, in increments of 30. This option is available in Preview. To use this option use the beta instances.inset method.
RESTART_POLICY: the restart policy for this VM, either true or false

Update host maintenance policy of a VM

Console

In the Google Cloud console, go to the VM instances page.

Go to VM instances
Click the VM for which you want to change settings. The VM details page displays.
On the VM details page, complete the following steps:
1. Click the Edit button at the top of the page.
2. Under Availability policies, update the policy as needed. From the Availability policies section, you can set the On host maintenance and Automatic restart options.
3. Click Save.

gcloud

To update the host maintenance policy of an existing VM, use the gcloud compute instances set-scheduling command with the same parameters and flags used in the VM creation command above.

gcloud compute instances set-scheduling VM_NAME \
     --maintenance-policy=MAINTENANCE_POLICY \
     --host-error-timeout-seconds=NUMBER_OF_SECONDS \
     [--no-restart-on-failure | --restart-on-failure]

Replace the following:

MAINTENANCE_POLICY: the policy for this VM, either TERMINATE or MIGRATE
VM_NAME: the VM name
NUMBER_OF_SECONDS: the number of seconds Compute Engine waits before restarting an unresponsive VM, between 90 and 330, in increments of 30. This option is available in Preview. To use this option use the gcloud beta compute instances set-scheduling command.

API

To update the host maintenance policy of an existing VM, use the instances.setScheduling method.

In the API, make a POST request to the following URL:

https://compute.googleapis.com/compute/v1/projects/PROJECT_IDt/zones/ZONE/instances/VM_NAME/setScheduling

Replace the following:

PROJECT_ID: the project where the VM is located
ZONE: the zone where the VM is located
VM_NAME: the VM name

Add the onHostMaintenance, hostErrorTimeoutSeconds, and automaticRestart parameters as part of the request body:

{
 "onHostMaintenance": "MAINTENANCE_POLICY",
 "hostErrorTimeoutSeconds": NUMBER_OF_SECONDS,
 "automaticRestart": RESTART_POLICY
}

Replace the following:

MAINTENANCE_POLICY: the policy for this VM, either TERMINATE or MIGRATE
NUMBER_OF_SECONDS: the number of seconds Compute Engine waits before restarting an unresponsive VM, between 90 and 330, in increments of 30. This option is available in Preview. To use this option use the beta instances().setScheduling method.
RESTART_POLICY: the restart policy for this VM, either true or false

What's next

Learn more about host maintenance.
Learn more about live migration.
Learn how to detect a live migration event.