Set the host maintenance policy for a compute instance

Linux Windows

This document explains how to set the host maintenance policy for aCompute Engine instance to determine its behavior during host events. Tolearn more about host maintenance policies, seeHost maintenance policy.

A host maintenance policy determines how your instance responds when the host onwhich the instance is running requires maintenance or encounters an error.Configuring the host maintenance policy for an instance helps you do thefollowing:

  • Minimize downtime.

  • Prevent data loss.

Limitations

For host maintenance policies, the following limitations apply:

  • Virtual machine instances using E2 machine types can only live migrateduring host maintenance events, unless they're Spot VMs orpreemptible VMs.

  • The following instances can only stop during host maintenance events:

    • Instances thatdon't support live migration,such as H4D instances, Z3 instances with more than 18 TiB of attachedTitanium SSD, bare metal instances, or VMs that have GPUs attached.

    • Spot VMs or preemptible VMs.

  • Spot VMs and preemptible VMs can't automatically restart afterhost errors or programmed stops.

Before you begin

Required roles

To get the permissions that you need to set the host maintenance policy for a compute instance, ask your administrator to grant you theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to set the host maintenance policy for a compute instance. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to set the host maintenance policy for a compute instance:

  • To create an instance:
    • compute.instances.create on the project
    • To use a custom image to create the VM:compute.images.useReadOnly on the image
    • To use a snapshot to create the VM:compute.snapshots.useReadOnly on the snapshot
    • To use an instance template to create the VM:compute.instanceTemplates.useReadOnly on the instance template
    • To assign alegacy network to the VM:compute.networks.use on the project
    • To specify a static IP address for the VM:compute.addresses.use on the project
    • To assign an external IP address to the VM when using a legacy network:compute.networks.useExternalIp on the project
    • To specify a subnet for the VM:compute.subnetworks.use on the project or on the chosen subnet
    • To assign an external IP address to the VM when using a VPC network:compute.subnetworks.useExternalIp on the project or on the chosen subnet
    • To set VM instance metadata for the VM:compute.instances.setMetadata on the project
    • To set tags for the VM:compute.instances.setTags on the VM
    • To set labels for the VM:compute.instances.setLabels on the VM
    • To set a service account for the VM to use:compute.instances.setServiceAccount on the VM
    • To create a new disk for the VM:compute.disks.create on the project
    • To attach an existing disk in read-only or read-write mode:compute.disks.use on the disk
    • To attach an existing disk in read-only mode:compute.disks.useReadOnly on the disk
  • To create an instance template:compute.instanceTemplates.create on the project
  • To update the host maintenance policy for an instance:compute.instances.setScheduling on the instance

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

Available host maintenance properties

You can customize how your compute instance behaves during scheduled maintenanceor unexpected host events. Unless you specify otherwise, Compute Engineuses default settings when you create aninstance, instances in bulk, or an instance template.

You can configure the following host maintenance properties:

  • Maintenance behavior (onHostMaintenance): what happens to yourinstance during a maintenance event on its host that might cause theinstance to restart. You can set this property to one of the following:

    • Migrate: Compute Engine automatically live migrates yourinstance to another host. This is the default setting for all types ofinstances, except Spot VMs and preemptible VMs.

      Important: You must configure instances thatdon't support live migrationto stop (Terminate) during maintenance events. Otherwise, youencounter errors.

    • Terminate: Compute Engine stops your instance. This is thedefault setting for Spot VMs or preemptible VMs, and it'sthe only supported setting for H4D instances, Z3 instances with morethan 18 TiB of attached Titanium SSD, bare metal instances, andinstances with GPUs or TPUs attached.

  • Automatic restart (automaticRestart): whether your instance restartsif it crashes or Compute Engine stops it for a programmed stop, suchas a maintenance event. You can set this property to one of the following:

    • On: Compute Engine automatically restarts the instance. Thisis the default setting for all types of instances, except forSpot VMs and preemptible VMs. You specify this setting asfollows:

      • For the Google Cloud console, in theAdvanced pane, in theAutomatic restart list, selectOn (recommended).

      • For the Google Cloud CLI, use the--restart-on-failure flag.

      • For REST, set theautomaticRestart field totrue.

    • Off: Compute Engine doesn't restart the instance. This isthe default setting for Spot VMs or preemptible VMs. Youspecify this setting as follows:

      • For the Google Cloud console, in theAdvanced pane, in theAutomatic restart list, selectOff.

      • For the gcloud CLI, use the--no-restart-on-failureflag.

      • For REST, set theautomaticRestart field tofalse.

  • Local SSD data recovery timeout (localSsdRecoveryTimeout): thissetting applies only to instances that have Local SSD disks attached. Itdetermines how long Compute Engine waits to recover data from yourLocal SSD disks after host errors. By default, this property is unset. Youcan set this property to one of the following:

    • Unset: Compute Engine uses the default wait time:

      • For Z3 VMs, 6 hours

      • For all other types of instances, 1 hour

    • An integer from 0 to 168: the number of hours to wait. Setting thisproperty to0 means that Compute Engine doesn't recover LocalSSD data and restarts the instance immediately.

  • Host error timeout (hostErrorTimeoutSeconds): this property determineshow long Compute Engine waits to restart an unresponsive instance.You must configure this setting before the instance becomes unresponsive.Use a timeout that is long enough for an instance to recover from beingunresponsive. You can set this property to one of the following:

    • Unset: Compute Engine waits up to 330 seconds (5 minutes and30 seconds). This is the default setting for any type of instance.

    • An integer from 90 to 330: the wait time in seconds, in incrementsof 30 seconds.

Set the host maintenance policy for an instance

By default, compute instances use thedefault settings for their hostmaintenance policy. To customize these settings, use one of the followingmethods:

Set the policy for an existing instance

Before you change the host maintenance policy of an existing instance, ensurethe following:

  • You can't change the maintenance behavior (onHostMaintenance) of thefollowing types of instances:

  • You can't configure Spot VMs or preemptible VMs toautomatically restart after host errors or programmed stops.

To change the Local SSD data recovery timeout in an instance that has Local SSDdisks attached, use the gcloud CLI or REST API. Otherwise,select any of the following options:

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. In theName column, click the name of the instance that you want toupdate. A page that gives the details of the instance appears.

  3. ClickEdit. A page thatlets you edit instance properties appears.

  4. In theManagement section, you can do one or more of the following:

    • To change the behavior during maintenance events, select anotheroption from theOn host maintenance list

    • To change the timeout period before restarting an unresponsiveinstance, select another option from theHost error timeoutlist.

    • To change whether to restart the instance or not after host errorsor programmed stops, select another option from theAutomatic restart list.

  5. ClickSave.

gcloud

To change the host maintenance policy in an existing instance, use thegcloud compute instances set-scheduling commandwith one or more of the following flags:

  • To change host maintenance behavior, include the--maintenance-policyflag.

  • To change automatic restart behavior, do one of the following:

    • To automatically restart the instance, include the--restart-on-failure flag.

    • To prevent the instance from automatically restarting, include the--no-restart-on-failure flag.

  • To change the Local SSD data recovery timeout if your instance has LocalSSD disks attached, include the--local-ssd-recovery-timeout flag.

  • To change the host error timeout, include the--host-error-timeout-seconds flag.

For example, to change host maintenance behavior, automatically restart theinstance after host errors or programmed stops, change the Local SSD datarecovery timeout, and change the host error timeout, run the followingcommand:

gcloud compute instances set-schedulingINSTANCE_NAME \    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \    --maintenance-policy=MAINTENANCE_POLICY \    --restart-on-failure \    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of your instance.

  • ERROR_DETECTION_TIMEOUT: the number of seconds beforeCompute Engine restarts an unresponsive instance. The value mustbe between90 (90 seconds) and330 (330 seconds, or 5 minutes and 30seconds). Only 30-second increments are allowed.

  • MAINTENANCE_POLICY: the maintenance behavior of theinstance. The value can be eitherTERMINATE orMIGRATE.

  • LOCAL_SSD_RECOVERY_TIMEOUT: the number of hours tospend recovering data from the attached Local SSD disks. The value mustbe between0 (0 hours) and168 (168 hours, or 7 days). Setting thisfield to0 means that Compute Engine doesn't recover LocalSSD data.

  • ZONE: the zone where your instance exists.

REST

To change the host maintenance policy in an existing instance, make aPOSTrequest to theinstances.setScheduling method.In the request body, include one or more of the following fields:

  • To change host maintenance behavior, include theonHostMaintenancefield.

  • To change automatic restart behavior, do one of the following:

    • To automatically restart the instance, include theautomaticRestart field.

    • To prevent the instance from automatically restarting, include theautomaticRestart field.

  • To change the Local SSD data recovery timeout if your instance has LocalSSD disks attached, include thelocalSsdRecoveryTimeout field.

  • To change the host error timeout, include thehostErrorTimeoutSecondsfield.

For example, to change host maintenance behavior, automatically restart theinstance after host errors or programmed stops, change the Local SSD datarecovery timeout, and change the host error timeout, make a request asfollows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/setScheduling{  "automaticRestart":AUTOMATIC_RESTART,  "hostErrorTimeoutSeconds":ERROR_DETECTION_TIMEOUT,  "localSsdRecoveryTimeout":LOCAL_SSD_RECOVERY_TIMEOUT,  "onHostMaintenance": "MAINTENANCE_POLICY"}

Replace the following:

  • PROJECT_ID: the ID of the project where your instanceexists.

  • ZONE: the zone where your instance exists.

  • INSTANCE_NAME: the name of your instance.

  • AUTOMATIC_RESTART: the automatic restart behavior ofthe instance if it crashes or Compute Engine stops it for aprogrammed stop. Specify one of the following values:

    • To let Compute Engine automatically restart your instance:true

    • To prevent automatic restarts:false

  • ERROR_DETECTION_TIMEOUT: the number of seconds beforerestarting an unresponsive instance. The value must be between90 (90seconds) and330 (330 seconds, or 5 minutes and 30 seconds). Only30-second increments are allowed.

  • LOCAL_SSD_RECOVERY_TIMEOUT: the number of hours tospend recovering data from the attached Local SSD disks. The value mustbe between0 (0 hours) and168 (168 hours, or 7 days). Setting thisfield to0 means that Compute Engine doesn't recover LocalSSD data.

  • MAINTENANCE_POLICY: the maintenance behavior of theinstance. The value can be eitherTERMINATE orMIGRATE.

Set the policy while creating an instance

You can set the host maintenance policy of a compute instance while creating it.

To set the Local SSD data recovery timeout while creating an instance that hasLocal SSD disks attached, use the gcloud CLI or REST API.Otherwise, select any of the following options:

Console

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

    Go to Create an instance

  2. In theName field, enter a name for the instance.

  3. In theRegion andZone fields, specify in which region and zoneto create the instance.

  4. Specify the machine type for the instance.

  5. In the navigation menu, clickAdvanced.

  6. In theProvisioning model section, expandVM provisioning model advanced settings, and then do one or moreof the following:

    • To set the behavior during maintenance events, in theOn host maintenance list, select one of the following options:

      • To migrate the instance during host maintenance events, selectMigrate VM instance (recommended).

      • To stop the instance during host maintenance events, selectTerminate VM instance.

    • To set the timeout period before restarting an unresponsiveinstance, in theHost error timeout list, select one of thefollowing options:

      • To not specify a host error timeout, selectUnspecified (default).

      • To specify a host error timeout, select one of the availableoptions, up to5 minutes and 30 seconds.

    • To set whether to restart the instance if it crashes or isstopped, In theAutomatic restart list, select one of thefollowing options:

      • To automatically restart the instance after host errors orprogrammed stops, selectOn (recommended).

      • To prevent the instance from automatically restarting after hosterrors or programmed stops, selectOff.

  7. ClickCreate.

gcloud

To set the host maintenance policy of an instance while creating it, use thegcloud compute instances create commandwith one or more of the following flags:

  • To set the host maintenance behavior, include the--maintenance-policyflag.

  • To set the automatic restart behavior, do one of the following:

    • To automatically restart the instance, include the--restart-on-failure flag.

    • To prevent the instance from automatically restarting, include the--no-restart-on-failure flag.

  • To set a Local SSD data recovery timeout if your instance has Local SSDdisks attached, include the--local-ssd-recovery-timeout flag.

  • To set a host error timeout, include the--host-error-timeout-secondsflag.

For example, to set the host maintenance behavior, automatically restart theinstance after host errors or programmed stops, set a Local SSD datarecovery timeout, and set a host error timeout, run the following command:

Important: Spot VMs and preemptible VMs don't supportautomatic restarts after host errors or programmed stops. If you include the--restart-on-failure flag when you create these types of VMs, thenCompute Engine ignores it. This behavior is the same as using the--no-restart-on-failure flag.
gcloud compute instances createINSTANCE_NAME \    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \    --machine-type=MACHINE_TYPE \    --maintenance-policy=MAINTENANCE_POLICY \    --restart-on-failure \    --zone=ZONE

Replace the following:

REST

To set the host maintenance policy of an instance while creating it, make aPOST request to theinstances.insert method.In the request body, include one or more of the following fields in thescheduling field:

  • To set the host maintenance behavior, include theonHostMaintenancefield.

  • To set the automatic restart behavior, do one of the following:

    • To automatically restart the instance, include theautomaticRestart field.

    • To prevent the instance from automatically restarting, include theautomaticRestart field.

  • To set a Local SSD data recovery timeout if your instance has Local SSDdisks attached, include thelocalSsdRecoveryTimeout field.

  • To set a host error timeout, include thehostErrorTimeoutSecondsfield.

For example, to set the host maintenance behavior, automatically restart theinstance after host errors or programmed stops, set a Local SSD datarecovery timeout, and set a host error timeout, make a request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "name": "INSTANCE_NAME",  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"      }    }  ],  "networkInterfaces": [    {      "network": "global/networks/default"    }  ],  "scheduling": {    "automaticRestart":AUTOMATIC_RESTART,    "hostErrorTimeoutSeconds":ERROR_DETECTION_TIMEOUT,    "localSsdRecoveryTimeout":LOCAL_SSD_RECOVERY_TIMEOUT,    "onHostMaintenance": "MAINTENANCE_POLICY"  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createthe instance.

  • ZONE: the zone in which to create the instance.

  • INSTANCE_NAME: the name of the instance.

  • MACHINE_TYPE: the machine type to use.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This specifiesthe most recent, non-deprecated OS image. For example, if youspecifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • AUTOMATIC_RESTART: the automatic restart behavior ofthe instance if it crashes or Compute Engine stops it for aprogrammed stop. Specify one of the following values:

    • To let Compute Engine automatically restart your instance:true

    • To prevent automatic restarts:false

  • ERROR_DETECTION_TIMEOUT: the number of seconds beforerestarting an unresponsive instance. The value must be between90 (90seconds) and330 (330 seconds, or 5 minutes and 30 seconds). Only30-second increments are allowed.

  • LOCAL_SSD_RECOVERY_TIMEOUT: the number of hours to spendrecovering data from the attached Local SSD disks. The value must bebetween0 (0 hours) and168 (168 hours, or 7 days). Setting thisfield to0 means that Compute Engine doesn't recover LocalSSD data.

  • MAINTENANCE_POLICY: the maintenance behavior of theinstance. The value can be eitherTERMINATE orMIGRATE. If you'recreating a Spot VM or an instance thatdoesn't support live migration,then you can only useTERMINATE.

For more information about creating an instance, seeCreate and start a Compute Engine instance.

Set the policy while creating instances in bulk

To set the host maintenance policy while creating instances in bulk, select oneof the following options:

gcloud

To set the host maintenance policy while creating instances in bulk, use thegcloud compute instances bulk create commandwith one or more of the following flags:

  • To set the host maintenance behavior, include the--maintenance-policyflag.

  • To set the automatic restart behavior, do one of the following:

    • To automatically restart the instance, include the--restart-on-failure flag.

    • To prevent the instance from automatically restarting, include the--no-restart-on-failure flag.

  • To set a Local SSD data recovery timeout if your instance has Local SSDdisks attached, include the--local-ssd-recovery-timeout flag.

  • To set a host error timeout, include the--host-error-timeout-secondsflag.

For example, to set the host maintenance behavior, automatically restart theinstance after host errors or programmed stops, set a Local SSD datarecovery timeout, and set a host error timeout, run the following command.The following example also creates instances in a single zone and specifiesa name pattern for the instances:

Important: Spot VMs and preemptible VMs don't supportautomatic restarts after host errors or programmed stops. If you include the--restart-on-failure flag when you create these types of VMs, thenCompute Engine ignores it. This behavior is the same as using the--no-restart-on-failure flag.
gcloud compute instances bulk create \    --count=COUNT \    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \    --machine-type=MACHINE_TYPE \    --maintenance-policy=MAINTENANCE_POLICY \    --name-pattern=NAME_PATTERN \    --restart-on-failure \    --zone=ZONE

Replace the following:

REST

To set the host maintenance policy while creating instances in bulk, make aPOST request to theinstances.bulkInsert method.In the request body, include one or more of the following fields in thescheduling field:

  • To set the host maintenance behavior, include theonHostMaintenancefield.

  • To set the automatic restart behavior, do one of the following:

    • To automatically restart the instance, include theautomaticRestart field.

    • To prevent the instance from automatically restarting, include theautomaticRestart field.

  • To set a Local SSD data recovery timeout if your instance has Local SSDdisks attached, include thelocalSsdRecoveryTimeout field.

  • To set a host error timeout, include thehostErrorTimeoutSecondsfield.

For example, to set the host maintenance behavior, automatically restart theinstance after host errors or programmed stops, set a Local SSD datarecovery timeout, and set a host error timeout, make a request as follows.The following example also creates instances in a single zone and specifiesa name pattern for the instances:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert{  "count":COUNT,  "namePattern": "NAME_PATTERN",  "instanceProperties": {    "machineType": "MACHINE_TYPE",    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "scheduling": {      "automaticRestart":AUTOMATIC_RESTART,      "hostErrorTimeoutSeconds":ERROR_DETECTION_TIMEOUT,      "localSsdRecoveryTimeout":LOCAL_SSD_RECOVERY_TIMEOUT,      "onHostMaintenance": "MAINTENANCE_POLICY"    }  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createthe instances.

  • ZONE: the zone in which to create the instances.

  • COUNT: the number of instances to create.

  • NAME_PATTERN: the name pattern for the instances. Toreplace a sequence of numbers in an instance name, use a sequence ofhash (#) characters. For example, usinginstance-# for the namepattern generates instances with names starting withinstance-1,instance-2, and continuing up to the number of instance specified byCOUNT.

  • MACHINE_TYPE: the machine type to use.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This specifiesthe most recent, non-deprecated OS image. For example, if youspecifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • AUTOMATIC_RESTART: the automatic restart behavior ofthe instance if it crashes or Compute Engine stops it for aprogrammed stop. Specify one of the following values:

    • To let Compute Engine automatically restart your instance:true

    • To prevent automatic restarts:false

  • ERROR_DETECTION_TIMEOUT: the number of seconds beforerestarting an unresponsive instance. The value must be between90 (90seconds) and330 (330 seconds, or 5 minutes and 30 seconds). Only30-second increments are allowed.

  • LOCAL_SSD_RECOVERY_TIMEOUT: the number of hours to spendrecovering data from the attached Local SSD disks. The value must bebetween0 (0 hours) and168 (168 hours, or 7 days). Setting thisfield to0 means that Compute Engine doesn't recover LocalSSD data.

  • MAINTENANCE_POLICY: the maintenance behavior of theinstances. The value can be eitherTERMINATE orMIGRATE. If you'recreating Spot VMs, preemptible VMs, or instances thatdon't support live migration,then you can only useTERMINATE.

For more information about creating instances in bulk, seeCreate VMs in bulk.

Set the policy while creating an instance template

You can set the host maintenance policy while creating an instance template. Allcompute instances that you create using the template inherit the hostmaintenance policy specified in the template.

To set the Local SSD data recovery timeout while creating an instance templatethat specifies Local SSD disks, use the gcloud CLI or RESTAPI. Otherwise, select any of the following options:

Console

  1. In the Google Cloud console, go to theInstance templates page.

    Go to Instance templates

  2. ClickCreate instance template. TheCreate instance templatepage appears.

  3. In theName field, enter a name for the instance template.

  4. In theLocation section, select one of the following options:

    • To create a regional instance template, selectRegional (recommended), and then select the region in which tocreate the template.

    • To create a global instance template, selectGlobal.

  5. In theMachine configuration section, specify the machine type forthe instance template.

  6. In theProvisioning model section, expandVM provisioning model advanced settings, and then do one or moreof the following:

    • To change the behavior during maintenance events, in theOn host maintenance list, select one of the following options:

      • To migrate the instance during host maintenance events, selectMigrate VM instance (recommended).

      • To stop the instance during host maintenance events, selectTerminate VM instance.

    • To change the timeout period before restarting an unresponsiveinstance, in theHost error timeout list, select one of thefollowing options:

      • To not specify a host error timeout, selectUnspecified (default).

      • To specify a host error timeout, select one of the availableoptions, up to5 minutes and 30 seconds.

    • To change whether to restart the instance if it crashes or isstopped, In theAutomatic restart list, select one of thefollowing options:

      • To automatically restart the instance after host errors orprogrammed stops, selectOn (recommended).

      • To prevent the instance from automatically restarting after hosterrors or programmed stops, selectOff.

  7. ClickCreate.

gcloud

To set the host maintenance policy while creating an instance template, usethegcloud compute instance-templates create commandwith one or more of the following flags:

  • To set the host maintenance behavior, include theonHostMaintenancefield.

  • To set the automatic restart behavior, do one of the following:

    • To automatically restart the instance, include theautomaticRestart field.

    • To prevent the instance from automatically restarting, include theautomaticRestart field.

  • To set a Local SSD data recovery timeout if your instance has Local SSDdisks attached, include thelocalSsdRecoveryTimeout field.

  • To set a host error timeout, include thehostErrorTimeoutSecondsfield.

For example, to set the host maintenance behavior, automatically restart theinstance after host errors or programmed stops, set a Local SSD datarecovery timeout, and set a host error timeout, run the following command.The following example also creates a regional instance template. To create aglobal instance template, use the same command without the--instance-template-region flag.

Important: Spot VMs and preemptible VMs don't supportautomatic restarts after host errors or programmed stops. If you include the--restart-on-failure flag when you create these types of VMs, thenCompute Engine ignores it. This behavior is the same as using the--no-restart-on-failure flag.
gcloud compute instance-templates createINSTANCE_TEMPLATE_NAME \    --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT \    --instance-template-region=REGION \    --local-ssd-recovery-timeout=LOCAL_SSD_RECOVERY_TIMEOUT \    --machine-type=MACHINE_TYPE \    --maintenance-policy=MAINTENANCE_POLICY \    --restart-on-failure

Replace the following:

REST

To set the host maintenance policy while creating an instance template, makeaPOST request to one of the following methods:

In the request body, include one or more of the following fields in thescheduling field:

  • To set the host maintenance behavior, include theonHostMaintenancefield.

  • To set the automatic restart behavior, do one of the following:

    • To automatically restart the instance, include theautomaticRestart field.

    • To prevent the instance from automatically restarting, include theautomaticRestart field.

  • To set a Local SSD data recovery timeout if your instance has Local SSDdisks attached, include thelocalSsdRecoveryTimeout field.

  • To set a host error timeout, include thehostErrorTimeoutSecondsfield.

For example, to set the host maintenance behavior, automatically restart theinstance after host errors or programmed stops, set a Local SSD datarecovery timeout, and set a host error timeout, make a request as follows.The following example also creates a regional instance template.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceTemplates{  "name": "INSTANCE_TEMPLATE_NAME",  "properties": {    "disks": [      {        "boot": true,        "initializeParams": {          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"        }      }    ],    "machineType": "MACHINE_TYPE",    "networkInterfaces": [      {        "network": "global/networks/default"      }    ],    "scheduling": {      "automaticRestart":AUTOMATIC_RESTART,      "hostErrorTimeoutSeconds":ERROR_DETECTION_TIMEOUT,      "localSsdRecoveryTimeout":LOCAL_SSD_RECOVERY_TIMEOUT,      "onHostMaintenance": "MAINTENANCE_POLICY"    }  }}

Replace the following:

  • PROJECT_ID: the ID of the project in which to createthe instance template.

  • REGION: the region in which to create the instancetemplate.

  • INSTANCE_TEMPLATE_NAME: the name of the instancetemplate.

  • IMAGE_PROJECT: the image project that contains theimage—for example,debian-cloud. For more information about thesupported image projects, seePublic images.

  • IMAGE: specify one of the following:

    • A specific version of the OS image—for example,debian-12-bookworm-v20240617.

    • Animage family, which must beformatted asfamily/IMAGE_FAMILY. This specifiesthe most recent, non-deprecated OS image. For example, if youspecifyfamily/debian-12, the latest version in the Debian 12image family is used. For more information about using imagefamilies, seeImage families best practices.

  • MACHINE_TYPE: the machine type to use.

  • AUTOMATIC_RESTART: the automatic restart behavior ofthe instance if it crashes or Compute Engine stops it for aprogrammed stop. Specify one of the following values:

    • To let Compute Engine automatically restart your instance:true

    • To prevent automatic restarts:false

  • ERROR_DETECTION_TIMEOUT: the number of seconds beforerestarting an unresponsive instance. The value must be between90 (90seconds) and330 (330 seconds, or 5 minutes and 30 seconds). Only30-second increments are allowed.

  • LOCAL_SSD_RECOVERY_TIMEOUT: the number of hours tospend recovering data from the attached Local SSD disks. The value mustbe between0 (0 hours) and168 (168 hours, or 7 days). Setting thisfield to0 means that Compute Engine doesn't recover LocalSSD data.

  • MAINTENANCE_POLICY: the maintenance behavior of theinstances. The value can be eitherTERMINATE orMIGRATE. If you'respecifying a Spot VM, preemptible VM, or instance typethatdoesn't support live migrationin the instance template, then you can only useTERMINATE.

For more information about creating an instance template, seeCreate instance templates.

View host maintenance policy of an instance

You can view the host maintenance policy of an instance byviewing the instance's details.

When viewing the instance's details using the gcloud CLI orREST API, you can only view thelocalSsdRecoveryTimeout andhostErrorTimeoutSeconds fields if you specified themwhile creating or updating the instance.

To view the Local SSD data recovery timeout in an instance that has Local SSDdisks attached, use the gcloud CLI or REST API. Otherwise,select any of the following options:

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. In theName column, click the instance that you want to view. A pagethat gives the details of the instance appears.

  3. On theDetails tab, in theManagement section, in theAvailability policies section, you can view the following:

    • In theOn host maintenance field, you can see the instance'shost maintenance behavior events.

    • In theHost error timeout field, you can see the amount of timethe instance waits before restarting or stopping the instance afterdetecting that it's unresponsive. If the value is unset(—), then the default wait time is 5 minutes and 30seconds.

    • In theAutomatic restart restart field, you can see whether theinstance automatically restarts the instance after it crashes orCompute Engine stops it for a programmed stop.

gcloud

To view the host maintenance policy for an instance, use thegcloud compute instances describe commandwith the--flatten flag set toscheduling:

 gcloud compute instances describeINSTANCE_NAME \    --flatten=scheduling \    --zone=ZONE

Replace the following:

  • INSTANCE_NAME: the name of the instance.

  • ZONE: the zone where the instance is located.

The output is similar to the following:

---scheduling:  automaticRestart: true  hostErrorTimeoutSeconds: 120  localSsdRecoveryTimeout:    nanos: 0    seconds: '10800'  onHostMaintenance: MIGRATE  preemptible: false  provisioningModel: STANDARD

REST

To view the host maintenance policy for an instance, make aGET request totheinstances.get method.In the request URL, include thefields query parameter and set it toscheduling:

  GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?fields=scheduling

Replace the following:

  • PROJECT_ID: the project where the instance exists.

  • ZONE: the zone where the instance exists.

  • INSTANCE_NAME: the name of the instance.

The output is similar to the following:

{  "scheduling": {    "onHostMaintenance": "MIGRATE",    "automaticRestart": true,    "preemptible": false,    "provisioningModel": "STANDARD",    "localSsdRecoveryTimeout": {      "seconds": "10800",      "nanos": 0    }  }}

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.