Set the host maintenance policy for an instance

Console

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

   Go to Create an instance

2. Specify a Name for the instance.

3. Select a Region and Zone for the instance.

4. In the Machine configuration section, do the following:

   1. Specify the details of the machine type for the instance.
   2. Expand the VM provisioning model advanced settings menu.
   3. In the On host maintenance menu, select one of the following steps:
      1. To migrate VMs during maintenance events, select Migrate VM instance.
      2. To stop instances during maintenance events, select Terminate VM instance.

5. To create the instance, click Create.

gcloud

To set the host maintenance policy of a new instance, use the gcloud compute instances create command.

To set the --host-error-timeout-seconds property (Preview), you must use the gcloud beta compute instances create command.

You can set the host maintenance policy of a new instance with the following command. If you omit any of the flags, the default value for the flag is used.

  gcloud compute instances create INSTANCE_NAME \
      --zone=ZONE \
      --maintenance-policy=MAINTENANCE_BEHAVIOR \
      --RESTART_ON_FAILURE_BEHAVIOR \
      --local-ssd-recovery-timeout=SSD_RECOVERY_TIMEOUT \
      --host-error-timeout-seconds=ERROR_DETECTION_TIMEOUT

Replace the following:

• INSTANCE_NAME: the instance name.
• ZONE: the zone where the instance is located,
• MAINTENANCE_BEHAVIOR: the maintenance event behavior of an instance, either TERMINATE or MIGRATE. For most machine types, the VM is migrated by default if you omit this property. Z3 and bare metal instances terminate.
• RESTART_ON_FAILURE_BEHAVIOR: Restart behaviour for terminated or unresponsive instances, set to either restart-on-failure (default) or no-restart-on-failure.
• SSD_RECOVERY_TIMEOUT: the number of hours to spend recovering Local SSD disks attached to a terminated or unresponsive instance. Valid values are from 0 to 168, in increments of 1 hour.
• ERROR_DETECTION_TIMEOUT: the number of seconds Compute Engine waits before restarting an unresponsive instance, from 90 to 330 seconds (5.5 minutes), in 30-second increments.

REST

To set the host maintenance policy of a new instance using REST, use the instances.insert method.

You can set the host maintenance policy of a new instance with the following command. If you omit any of the fields, the default value for the field is used.

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

      {
        "name": "INSTANCE_NAME",

        "scheduling": {
          "onHostMaintenance": "MAINTENANCE_BEHAVIOR",
          "automaticRestart": "RESTART_POLICY,
          "localSsdRecoveryTimeout": SSD_RECOVERY_TIMEOUT
        }
      }

Replace the following:

• PROJECT_ID: the project for the instance.
• ZONE: the zone where you want to create the instance.
• INSTANCE_NAME: the instance name.
• MAINTENANCE_BEHAVIOR: the maintenance event behavior of an instance, either TERMINATE or MIGRATE. For most machine types, the VM is migrated by default if you omit this field. Z3 and bare metal instances terminate.
• RESTART_POLICY: whether the instance restarts automatically after a maintenance event or a host error, either true (default) or false.
• SSD_RECOVERY_TIMEOUT: the number of hours Compute Engine spends recovering any Local SSD disks attached to an unresponsive or terminated instance. Valid values are from 0 to 168, in increments of 1 hour. The default value for Z3 is 6 hours, and for all other VMs the default is 1 hour.

Set the host error detection timeout

To set the maximum amount of time Compute Engine waits to restart or terminate an unresponsive instance, use the beta instances.insert method because this option is in Preview.

Add the hostErrorTimeoutSeconds property to the scheduling object of the request body, where HOST_ERROR_TIMEOUT is the number of seconds that Compute Engine waits before restarting or terminating an unresponsive instance. Valid values are from 90 to 330 (5.5 minutes), in 30-second increments.

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

   {
      "name": "INSTANCE_NAME",

      "scheduling": {
        "onHostMaintenance": "MAINTENANCE_BEHAVIOR",
        "automaticRestart": "RESTART_POLICY,
        "localSsdRecoveryTimeout": SSD_RECOVERY_TIMEOUT
        "hostErrorTimeoutSeconds": HOST_ERROR_TIMEOUT,
      }
    }

Console

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

   Go to VM instances

2. Click the name of the instance for which you want to change settings. The instance details page displays.

3. With the Details tab selected, complete the following steps:

   1. Click the Edit button at the top of the page.
   2. Go to the Management section. In the Availability policies section, you can change the host maintenance options.
   3. Click Save.

gcloud

Update the host maintenance policy of an existing instance with the gcloud compute instances set-scheduling command. Use the same parameters as for the instance creation command in the preceding section.

To update the maximum amount of time Compute Engine waits to restart or terminate an unresponsive instance (Preview), use the gcloud beta compute instances set-scheduling command and include --host-error-timeout-seconds=NUMBER_OF_SECONDS.

    gcloud compute instances set-scheduling INSTANCE_NAME \
      --maintenance-policy=MAINTENANCE_BEHAVIOR \
      --RESTART_ON_FAILURE_BEHAVIOR \
      --local-ssd-recovery-timeout=SSD_RECOVERY_TIMEOUT

Replace the following:

• NUMBER_OF_SECONDS: the number of seconds Compute Engine waits before restarting or terminating an unresponsive VM, from 90 to 330 (5.5 minutes), in 30-second increments.
  • INSTANCE_NAME: the instance name.
  • MAINTENANCE_BEHAVIOR: the maintenance event behavior of an instance, either TERMINATE or MIGRATE. For most machine types, the VM is migrated by default if you omit this property. Z3 and bare metal instances terminate.
  • RESTART_ON_FAILURE_BEHAVIOR: Restart behaviour for terminated or unresponsive instances, set to either restart-on-failure (default) or no-restart-on-failure.
  • SSD_RECOVERY_TIMEOUT: the number of hours to spend recovering Local SSD disks attached to a terminated or unresponsive instance. Valid values are from 0 to 168, in increments of 1 hour.
  • NUMBER_OF_SECONDS: the number of seconds Compute Engine waits before restarting an unresponsive instance, from 90 to 330 seconds (5.5 minutes), in 30-second increments.

REST

Update the host maintenance policy of an existing instance using a POST request to the instances.setScheduling method.

    POST https://compute.googleapis.com/compute/v1projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/setScheduling

    {
      "onHostMaintenance": "MAINTENANCE_BEHAVIOR",
      "automaticRestart": RESTART_POLICY,
      "localSsdRecoveryTimeout": SSD_RECOVERY_TIMEOUT
    }

Replace the following:

• PROJECT_ID: the project for the instance.
• ZONE: the zone where the instance is located.
• INSTANCE_NAME: the instance name.
• MAINTENANCE_BEHAVIOR: the maintenance event behavior of this instance, either TERMINATE or MIGRATE.
• RESTART_POLICY: whether the instance is automatically restarted, either true or false.
  • SSD_RECOVERY_TIMEOUT: the number of hours to spend recovering Local SSD disks attached to the instance. Valid values are from 0 to 168, in increments of 1 hour.

Update the host error detection timeout

To update the maximum amount of time Compute Engine waits to restart or terminate an unresponsive VM, you must use the beta instances.setScheduling method because this feature is in Preview.

Add the hostErrorTimeoutSeconds property to request body, where HOST_ERROR_TIMEOUT is the number of seconds that Compute Engine waits before restarting or terminating an unresponsive instance. Valid values are from 90 to 330 (5.5 minutes), in 30-second increments.

  POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME/setScheduling

  {
    ...
    "hostErrorTimeoutSeconds": NUMBER_OF_SECONDS
  }

Console

1. Go to the VM instances page.

   Go to VM instances

2. Click the Name of the instance for which you want to view settings. The instance details page opens.

3. Go to the Management section. The Availability policies subsection shows your current settings for the following:

   • On host maintenance
   • Automatic restart
   • Host error timeout

gcloud

View the host maintenance option settings for an instance with the gcloud compute instances describe command.

To view the current value of the hostErrorTimeoutSeconds setting (Preview), use the gcloud beta compute instances describe command.

 gcloud compute instances describe INSTANCE_NAME \
 --zone ZONE --format="yaml(scheduling)"

Replace the following:

• INSTANCE_NAME: the name of the instance
• ZONE: the zone where the instance is located

The output includes the current settings for the host maintenance policy, for example:

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

REST

To view the host maintenance settings for an instance, use the instances.get method:

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

Replace the following:

• PROJECT_ID: the project where the instance is located.
• ZONE: the zone where the instance is located.
• INSTANCE_NAME: the instance name.

In the output, the scheduling object contains the settings for the instance's host maintenance policy, for example:

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

View the host error timeout settings

View the current hostErrorTimeoutSeconds setting by constructing a GET request using the beta instances.get method.

 GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME

Replace the following:

• PROJECT_ID: the project for the instance.
• ZONE: the zone where the instance is located.
• INSTANCE_NAME: the instance name.

In the output, the scheduling object includes the instance's host error detection timeout, for example:

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