Create and apply spread placement policies to VMs

This document explains how to create a spread placement policy and apply it to one or more virtual machine (VM) instances for improved reliability.

A spread placement policy specifies that your VMs should be physically placed far apart from each other by placing them in different availability domains. Use a spread placement policy to ensure that your VMs are placed on distinct hardware, reducing the impact of underlying hardware failures or optimizing live migration.

Before you begin

  • If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

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

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    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, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to create and apply a spread placement policy to VMs, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to create and apply a spread placement policy to VMs. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create and apply a spread placement policy to VMs:

  • To create placement policies: compute.resourcePolicies.create on the project
  • To apply a placement policy to existing VMs: compute.instances.addResourcePolicies on the project
  • To create VMs:
    • 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 a legacy 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 create a regional or zonal managed instance group (MIG): compute.instanceGroupManagers.create on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Create a spread placement policy

When creating a spread placement policy, you can specify up to eight availability domains to place your VMs in. Unless you want to test the application of the spread placement policy to your VMs, Google Cloud recommends specifying two or more availability domains. This mitigates the risk of all VMs being impacted by a single hardware failure.

To create a spread placement policy, select one of the following options:

gcloud

To create a spread placement policy, use the gcloud compute resource-policies create group-placement command with the --availability-domain-count flag.

gcloud compute resource-policies create group-placement POLICY_NAME \
    --availability-domain-count=DOMAIN_COUNT \
    --region=REGION

Replace the following:

  • POLICY_NAME: the name of the spread placement policy to create.

  • DOMAIN_COUNT: the distinct number of availability domains to place your VMs in. Each domain has its own independent power, cooling, and networking source. The value must be between 1 and 8, which is the maximum number of VMs you can apply a spread placement policy to.

  • REGION: the region where to create the policy.

REST

To create a spread placement policy, make a POST request to the resourcePolicies.insert method. In the request body, include the availabilityDomainCount field.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies

{
  "name": "POLICY_NAME",
  "groupPlacementPolicy": {
    "availabilityDomainCount": DOMAIN_COUNT
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project where you want to create the policy.

  • REGION: the region where you want to create the policy.

  • POLICY_NAME: the name of the spread placement policy to create.

  • DOMAIN_COUNT: the distinct number of availability domains to place your VMs in. Each domain has its own independent power, cooling, and networking source. The value must be between 1 and 8, which is the maximum number of VMs you can apply a spread placement policy to.

Apply spread placement policies

You can apply a spread placement policy to an existing VM, or when you create VMs, instance templates, or MIGs.

To create a Compute Engine resource that specifies a spread placement policy, or apply the spread placement policy to an existing VM, select one of the following methods:

Apply a spread placement policy to an existing VM

Before applying a spread placement policy to an existing VM, review the following:

  • If your spread placement policy has two or more availability domains, you can add it to a VM without stopping the VM. Otherwise, if your spread placement policy specifies only one domain, you must first stop the VM before applying the placement policy to it.

  • The VM and the spread placement policy must be located in the same region. For example, if the placement policy is located in region us-central1, then the VM must be located in a zone in us-central1. If you need to migrate a VM to another region, then see Move a VM between zones or regions.

Otherwise, applying the spread placement policy to the VM fails. If the VM already specifies a placement policy and you want to replace it, then see Replace a placement policy in a VM instead.

To apply a spread placement policy to an existing VM, select one of the following options:

gcloud

To apply a spread placement policy to an existing VM, use the gcloud compute instances add-resource-policies command with the --resource-policies flag.

gcloud compute instances add-resource-policies VM_NAME \
    --resource-policies=POLICY_NAME \
    --zone=ZONE

Replace the following:

  • VM_NAME: the name of an existing VM.

  • POLICY_NAME: the name of an existing spread placement policy.

  • ZONE: the zone where the VM exists, which must be within the region where the spread placement policy is located.

REST

To apply a spread placement policy to an existing VM, make a POST request to the instances.addResourcePolicies method. In the request body, include the resourcePolicies field.

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

{
  "resourcePolicies": [
    "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
  ]
}

Replace the following:

  • PROJECT_ID: the ID of the project where the spread placement policy and the VM are located.

  • ZONE: the zone where the VM exists, which must be within the region where the spread placement policy is located.

  • VM_NAME: the name of an existing VM.

  • REGION: the region where the spread placement policy is located.

  • POLICY_NAME: the name of an existing spread placement policy.

Create a VM with a spread placement policy

You can only create a VM with a spread placement policy in a zone within the same region as the placement policy.

To create a VM that specifies a spread placement policy, select one of the following options:

gcloud

To create a VM that specifies a spread placement policy, use the gcloud compute instances create command with the --resource-policies flag.

gcloud compute instances create VM_NAME \
    --machine-type=MACHINE_TYPE \
    --resource-policies=POLICY_NAME \
    --zone=ZONE

Replace the following:

  • VM_NAME: the name of the VM to create.

  • MACHINE_TYPE: the machine type for the VM.

  • POLICY_NAME: the name of an existing spread placement policy.

  • ZONE: the zone where to create the VM.

REST

To create a VM that specifies a spread placement policy, make a POST request to the instances.insert method. In the request body, include the resourcePolicies field.

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

{
  "name": "VM_NAME",
  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",
  "resourcePolicies": [
    "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
  ]
}

Replace the following:

  • PROJECT_ID: the ID of the project where the spread placement policy is located.

  • ZONE: the zone where to create the VM and where the machine type is located. You can only specify a machine type that is available within the same region as the spread placement policy.

  • VM_NAME: the name of the VM to create.

  • MACHINE_TYPE: the machine type for the VM.

  • REGION: the region where the spread placement policy is located.

  • POLICY_NAME: the name of an existing spread placement policy.

For more information about the configuration options to create a VM, see Create and start a VM instance.

Create VMs in bulk with a spread placement policy

You can only create VMs in bulk with a spread placement policy in the same region as the placement policy.

To create VMs in bulk that specify a spread placement policy, select one of the following options:

gcloud

To create VMs in bulk that specify a spread placement policy, use the gcloud compute instances bulk create command with the --resource-policies flag.

For example, to create VMs in bulk in a single zone and specify a name pattern for the VMs, run the following command:

gcloud compute instances bulk create \
    --count=COUNT \
    --machine-type=MACHINE_TYPE \
    --name-pattern=NAME_PATTERN \
    --resource-policies=POLICY_NAME \
    --zone=ZONE

Replace the following:

  • COUNT: the number of VMs to create.

  • MACHINE_TYPE: the machine type for the VMs.

  • NAME_PATTERN: the name pattern for the VMs to create. Use the hash character (#) to replace it with a sequence of numbers. For example, specifying vm-# creates VMs with names vm-1, vm-2, and so on, up to the number of VMs specified in COUNT.

  • POLICY_NAME: the name of an existing spread placement policy.

  • ZONE: the zone where to create the VMs in bulk.

REST

To create VMs in bulk that specify a spread placement policy, make a POST to the instances.bulkInsert method. In the request body, include the resourcePolicies field.

For example, to create VMs in bulk in a single zone and specify a name pattern for the VMs, make the following POST request:

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

{
  "count": "COUNT",
  "machineType": "MACHINE_TYPE",
  "namePattern": "NAME_PATTERN",
  "instanceProperties": {
    "resourcePolicies": [
      "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
    ]
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project where the spread placement policy is located.

  • ZONE: the zone where to create the VMs in bulk.

  • COUNT: the number of VMs to create.

  • MACHINE_TYPE: the machine type for the VMs.

  • NAME_PATTERN: the name pattern for the VMs to create. Use the hash character (#) to replace it with a sequence of numbers. For example, specifying vm-# for creates VMs with names vm-1, vm-2, and so on, up to the number of VMs specified in COUNT.

  • REGION: the region where the spread placement policy is located.

  • POLICY_NAME: the name of an existing spread placement policy.

For more information about the configuration options to create VMs in bulk, see Create VMs in bulk.

Create an instance template with a spread placement policy

If you want to create a regional instance template, then you must create the template in the same region as the spread placement policy. Otherwise, creating the instance template fails.

After you create an instance template, you can use it to do the following:

To create an instance template that specifies a spread placement policy, select one of the following options:

gcloud

To create an instance template that specifies a spread placement policy, use the gcloud compute instance-templates create command with the --resource-policies flag.

For example, to create a global instance template that specifies a spread placement policy, run the following command:

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --machine-type=MACHINE_TYPE \
    --resource-policies=POLICY_NAME

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the instance template.

  • MACHINE_TYPE: the machine type for the VMs created using the instance template.

  • POLICY_NAME: the name of an existing spread placement policy.

REST

To create an instance template that specifies a spread placement policy, make a POST request to the instanceTemplates.insert method. In the request body, include the resourcePolicies field.

For example, to create a global instance template that specifies a spread placement policy, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/instanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "properties": {
    "disks": [
      {
        "boot": true,
        "mode": "READ_WRITE",
        "type": "PERSISTENT",
        "initializeParams": {
          "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"
        }
      }
    ],
    "machineType": "MACHINE_TYPE",
    "networkInterfaces": [
      {
        "accessConfigs": [
          {
            "name": "external-IP",
            "type": "ONE_TO_ONE_NAT"
          }
        ],
        "network": "global/networks/default"
      }
    ],
    "resourcePolicies": {
      "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
    }
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project where the spread placement policy is located.

  • INSTANCE_TEMPLATE_NAME: the name of the instance template.

  • IMAGE or IMAGE_FAMILY: specify one of the following:

    • IMAGE: a specific version of the OS image; for example, debian-10-buster-v20200309.

    • IMAGE_FAMILY: an image family. This specifies the most recent, non-deprecated OS image. For example, if you specify family/debian-10, the latest version in the Debian 10 image family is used. For more information about using image families, see Image families best practices.

  • MACHINE_TYPE: the machine type for the VMs created using the instance template.

  • REGION: the region where the spread placement policy is located.

  • POLICY_NAME: the name of an existing spread placement policy.

For more information about the configuration options to create an instance template, see Create instance templates.

Apply a spread placement policy to the VMs in a MIG

After you create an instance template that specifies a spread placement policy, you can use the template to do the following:

If you want to apply a spread placement policy to a MIG, creating or applying the policy to a regional MIG with the any single zone distribution shape is recommended. This way, whenever a regional MIG needs to scale out by creating VMs, it selects the zone where to create the VMs based on your quotas and hardware requirements.

Create a MIG with a spread placement policy

You can only create VMs that specify a spread placement policy if the VMs are located in the same region as the placement policy.

To create a MIG using an instance template that specifies a spread placement policy, select one of the following options:

gcloud

To create a MIG using an instance template that specifies a spread placement policy, use the gcloud compute instance-groups managed create command.

For example, to create a regional MIG with default VM properties and the any-single-zone distribution shape, run the following command:

gcloud compute instance-groups managed create MIG_NAME \
    --region=REGION \
    --size=SIZE \
    --target-distribution-shape=any-single-zone \
    --template=INSTANCE_TEMPLATE_NAME

Replace the following:

  • MIG_NAME: the name of the MIG to create.

  • REGION: the region where to create the MIG, which must match with the region where the spread placement policy is located.

  • SIZE: the size of the MIG.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template that specifies a spread placement policy.

REST

To create a MIG using an instance template that specifies a spread placement policy, make a POST request to the instanceGroupManagers.insert or regionInstanceGroupManagers.insert methods.

For example, to create a regional MIG with default VM properties and the any-single-zone distribution shape, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers

{
  "name": "MIG_NAME",
  "instanceTemplate": "global/instanceTemplates/INSTANCE_TEMPLATE_NAME",
  "targetSize": SIZE,
  "distributionPolicy": {
    "targetShape": "ANY_SINGLE_ZONE"
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project where the spread placement policy and the instance template that specifies the placement policy are located.

  • REGION: the region where to create the MIG, which must match with the region where the spread placement policy is located.

  • MIG_NAME: the name of the MIG to create.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template that specifies a spread placement policy.

  • SIZE: the size of the MIG.

For more information about the configuration options to create MIGs, see Basic scenarios for creating MIGs.

Apply a spread placement policy to an existing MIG

You can only apply a compact placement policy to an existing MIG if the MIG is located in the same region as the placement policy or, for zonal MIGs, in a zone within the same region as the placement policy.

To update a MIG to use an instance template that specifies a spread placement policy, select one of the following options:

gcloud

To update a MIG to use an instance template that specifies a spread placement policy, use the gcloud compute instance-groups managed rolling-action start-update command.

For example, to update a regional MIG to use an instance template that specifies a spread placement policy and replace the existing VMs from the MIG with new VMs that specify the template's properties, run the following command:

gcloud compute instance-groups managed rolling-action start-update MIG_NAME \
    --region=REGION \
    --type=proactive \
    --version=template=INSTANCE_TEMPLATE_NAME

Replace the following:

  • MIG_NAME: the name of an existing MIG.

  • REGION: the region where the MIG is located. You can only apply the spread placement policy to a MIG that is in the same region.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template that specifies a spread placement policy.

REST

To update a MIG to use an instance template that specifies a spread placement policy, and automatically apply the properties of the template and the placement policy to existing VMs in the MIG, make a PATCH request to the instanceGroupManagers.insert or regionInstanceGroupManagers.insert methods.

For example, to update a regional MIG to use an instance template that specifies a spread placement policy and replace the existing VMs from the MIG with new VMs that specify the template's properties, make the following PATCH request:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/MIG_NAME

{
  "instanceTemplate": "global/instanceTemplates/INSTANCE_TEMPLATE_NAME",
  "updatePolicy": {
    "type": "PROACTIVE"
  }
}

Replace the following:

  • PROJECT_ID: the ID of the project you used to create an existing MIG, the spread placement policy, and the instance template that specifies the spread placement policy.

  • REGION: the region where the MIG is located. You can only apply the spread placement policy to a MIG that is in the same region.

  • MIG_NAME: the name of an existing MIG.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template that specifies a spread placement policy.

For more information about the configuration options to update the VMs in a MIG, see Update and apply new configurations to VMs in a MIG.

What's next?