Create and apply spread placement policies to VMs

This document describes how to improve the reliability of your virtual machine(VM) instances by creating and applying spread placement policies to them. Tolearn more about placement policies, including their restrictions and pricing,seePlacement policies overview.

A spread placement policy specifies that your VMs should be distributed acrossdifferent availability domains. This distribution helps mitigatelocation-specific disruptions, such as hardware errors, and is useful whenrunning large-scale, distributed, and replicated workloads like HadoopDistributed File System (HDFS), Cassandra, or Kafka.

Before you begin

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 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 create and apply a spread placement policy to VMs. To see the exact permissions that are required, expand theRequired 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 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 create a managed instance group (MIG):compute.instanceGroupManagers.create on the project

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

Create a spread placement policy

Unless you want to test the application of the spread placement policy to yourVMs, Google Cloud recommends creating spread placement policies with two or moreavailability domains. This mitigates the risk of all VMs being impacted by asingle hardware error. For more information, seeAbout spread placement policies.

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

gcloud

To create a spread placement policy, use thegcloud compute resource-policies create group-placement commandwith the--availability-domain-count flag.

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

Replace the following:

  • POLICY_NAME: the name of the spread placement policy.

  • DOMAIN_COUNT: the distinct number of availabilitydomains to place your VMs in. The value must be between1 and8.

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

REST

To create a spread placement policy, make aPOST request to theresourcePolicies.insert method.In the request body, include theavailabilityDomainCount 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 in which to createthe placement policy.

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

  • POLICY_NAME: the name of the spread placement policy.

  • DOMAIN_COUNT: the distinct number of availabilitydomains to place your VMs in. The value must be between1 and8.

Apply a spread placement policy

You can apply a spread placement policy to an existing VM or MIG, or whencreating VMs, instance templates, or MIGs.

To apply a spread placement policy to a Compute Engine resource, selectone of the following methods:

After you apply a spread placement policy to a VM, you can verify theavailability domain in which the VM is located byviewing the details of the VM andchecking the value of theavailabilityDomain field.

Apply the policy to an existing VM

Before applying a spread placement policy to an existing VM, consider thefollowing:

  • If your spread placement policy specifies multiple availability domains,then you can apply the policy to a VM without stopping the VM. However, theVM might need to be relocated to a different availability domain. Duringthis process, Compute Engine stops or live migrates the VM based onitshost maintenance policy.

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

If you want to specify the availability domain in which to place your VM, thenapply the placement policy to the VM byupdating its properties.When updating the VM's properties, make sure to include theresourcePoliciesandscheduling.availabilityDomain fields.

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

gcloud

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

gcloud compute instances add-resource-policiesVM_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 placementpolicy.

  • ZONE: the zone where the VM is located.

REST

To apply a spread placement policy to an existing VM, make aPOST requestto theinstances.addResourcePolicies method.

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 spreadplacement policy and the VM are located.

  • ZONE: the zone where the VM is located.

  • VM_NAME: the name of an existing VM.

  • REGION: the region where the spread placement policyis located.

  • POLICY_NAME: the name of an existing spread placementpolicy.

Apply the policy while creating a VM

You can only create a VM that specifies a spread placement policy in the sameregion as the placement policy.

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

gcloud

To create a VM that specifies a spread placement policy, use thegcloud compute instances create commandwith the--resource-policies flag.

gcloud compute instances createVM_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 placementpolicy.

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

Optionally, to specify the availability domain in which to create the VM,include the--availability-domain flag.

gcloud compute instances createVM_NAME \--availability-domain=DOMAIN_NUMBER \    --machine-type=MACHINE_TYPE \    --resource-policies=POLICY_NAME \    --zone=ZONE

ReplaceDOMAIN_NUMBER with the number of the availabilitydomain to place your VM in. The value must be between1 and the number ofdomains specified in the spread placement policy. To verify the number ofdomains in a spread placement policy,view the details of the placement policy.

REST

To create a VM that specifies a spread placement policy, make aPOSTrequest to theinstances.insert method.In the request body, include theresourcePolicies field.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "name": "VM_NAME",  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"      }    }  ],  "networkInterfaces": [    {      "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 spreadplacement policy is located.

  • ZONE: the zone where to create the VM in and wherethe machine type is located. You can only specify a zone within regionof the spread placement policy.

  • VM_NAME: the name of the VM to create.

  • MACHINE_TYPE: the machine type for the VM.

  • 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.

  • REGION: the region where the spread placement policyis located.

  • POLICY_NAME: the name of an existing spread placementpolicy.

Optionally, to specify the availability domain in which to create the VM,include theavailabilityDomain field in the request body.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances{  "name": "VM_NAME",  "machineType": "zones/ZONE/machineTypes/MACHINE_TYPE",  "disks": [    {      "boot": true,      "initializeParams": {        "sourceImage": "projects/IMAGE_PROJECT/global/images/IMAGE"      }    }  ],  "networkInterfaces": [    {      "network": "global/networks/default"    }  ],  "resourcePolicies": [    "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"  ],"scheduling": {    "availabilityDomain":DOMAIN_NUMBER  }}

ReplaceDOMAIN_NUMBER with the number of the availabilitydomain to place your VM in. The value must be between1 and the number ofdomains specified in the spread placement policy. To verify the number ofdomains in a spread placement policy,view the details of the placement policy.

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

Apply the policy while creating VMs in bulk

Before creating VMs in bulk that specify a spread placement policy, make sure ofthe following:

  • You can only create VMs in bulk that specify a spread placement policy inthe same region as the placement policy.

  • When creating VMs in bulk with a spread placement policy, you can optionallyspecify the availability domain in which to create your VMs. Avoid creatingall your VMs in a single domain. Otherwise, you don't mitigate the risk of asingle hardware error impacting all your VMs.

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

gcloud

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

For example, to create VMs in bulk in a single zone and specify a namepattern 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. Toreplace a sequence of numbers in a VM name, use a sequence of hash (#)characters. For example, usingvm-# for the name pattern generates VMswith names starting withvm-1,vm-2, and continuing up to the numberof VMs specified byCOUNT.

  • POLICY_NAME: the name of an existing spread placementpolicy.

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

Optionally, to specify the availability domain in which to create the VMs inbulk, include the--availability-domain flag.

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

ReplaceDOMAIN_NUMBER with the number of the availabilitydomain to place your VM in. The value must be between1 and the number ofdomains specified in the spread placement policy. To verify the number ofdomains in a spread placement policy,view the details of the placement policy.

REST

To create VMs in bulk that specify a spread placement policy, make aPOSTto theinstances.bulkInsert method.In the request body, include theresourcePolicies field.

For example, to create VMs in bulk in a single zone and specify a namepattern for the VMs, make aPOST request as follows:

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"      }    ],    "resourcePolicies": [      "POLICY_NAME"    ]  }}

Replace the following:

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

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

  • COUNT: the number of VMs to create.

  • NAME_PATTERN: the name pattern for the VMs. Toreplace a sequence of numbers in a VM name, use a sequence of hash (#)characters. For example, usingvm-# for the name pattern generates VMswith names starting withvm-1,vm-2, and continuing up to the numberof VMs specified byCOUNT.

  • MACHINE_TYPE: the machine type for the VMs.

  • 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.

  • POLICY_NAME: the name of an existing spread placementpolicy.

Optionally, to specify the availability domain in which to create the VMs inbulk, include theavailabilityDomain field in the request body.

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"      }    ],    "resourcePolicies": [      "POLICY_NAME"    ],"scheduling": {      "availabilityDomain":DOMAIN_NUMBER    }  }}

ReplaceDOMAIN_NUMBER with the number of the availabilitydomain to place your VM in. The value must be between1 and the number ofdomains specified in the spread placement policy. To verify the number ofdomains in a spread placement policy,view the details of the placement policy.

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

Apply the policy while creating an instance template

Before creating an instance template that specifies a spread placement policy,make sure of the following:

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

  • When creating an instance template, you can optionally specify theavailability domain in which to create VMs. Avoid creating all your VMs in asingle domain. Otherwise, you don't mitigate the risk of a single hardwareerror impacting all your VMs.

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

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

gcloud

To create an instance template that specifies a spread placement policy, usethegcloud compute instance-templates create commandwith the--resource-policies flag.

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

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

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the instancetemplate.

  • MACHINE_TYPE: the machine type for the VMs createdusing the instance template.

  • POLICY_NAME: the name of an existing spread placementpolicy.

Optionally, to specify the availability domain in which to create the VMs,include the--availability-domain flag.

gcloud compute instance-templates createINSTANCE_TEMPLATE_NAME \--availability-domain=DOMAIN_NUMBER  \    --machine-type=MACHINE_TYPE \    --resource-policies=POLICY_NAME

ReplaceDOMAIN_NUMBER with the number of the availabilitydomain to create your VMs in. The value must be between1 and the numberof domains specified in the placement policy. To verify the number ofdomains in a spread placement policy,view the details of the placement policy.

REST

To create an instance template that specifies a spread placement policy,make aPOST request to one of the following methods:

In the request body, specify theresourcePolicies field.

For example, to create a global instance template that specifies a spreadplacement policy, make aPOST request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/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"      }    ],    "resourcePolicies": [      "POLICY_NAME"    ]  }}

Replace the following:

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

  • 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 for the VMs createdusing the instance template.

  • POLICY_NAME: the name of an existing spread placementpolicy.

Optionally, to specify the availability domain in which to create the VMs,include theavailabilityDomain field in the request body.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/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"      }    ],    "resourcePolicies": [      "POLICY_NAME"    ],"scheduling": {      "availabilityDomain":DOMAIN_NUMBER    }  }}

ReplaceDOMAIN_NUMBER with the number of the availabilitydomain to create your VMs in. The value must be between1 and the numberof domains specified in the placement policy. To verify the number ofdomains in a spread placement policy,view the details of the placement policy.

For more information about the configuration options to create an instancetemplate, seeCreate instance templates.

Apply the policy to VMs in a MIG

After youcreate an instance template that specifies aspread placement policy, you can use the template to do the following:

Caution: Avoid using a spread placement policy (or its instance template) formultiple MIGs. A spread placement policy supportsa maximum of 256 VMs.If you share it among multiple MIGs, then the policy restricts the number of VMsthat you can create in the MIGs. Instead, use a new instance template with a newspread placement policy for each MIG.

Apply the policy while creating a MIG

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

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

gcloud

To create a MIG using an instance template that specifies a spreadplacement policy, use thegcloud compute instance-groups managed create command.

For example, to create a zonal MIG using a global instance template thatspecifies a spread placement policy, run the following command:

gcloud compute instance-groups managed createINSTANCE_GROUP_NAME \    --size=SIZE \    --template=INSTANCE_TEMPLATE_NAME \    --zone=ZONE

Replace the following:

  • INSTANCE_GROUP_NAME: the name of the MIG to create.

  • SIZE: the size of the MIG.

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

  • ZONE: the zone in which to create the MIG, whichmust be within the region where the spread placement policy is located.

REST

To create a MIG using an instance template that specifies a spread placementpolicy, make aPOST request to one of the following methods:

For example, to create a zonal MIG using a global instance template thatspecifies a spread placement policy, make aPOST request as follows:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers{  "name": "INSTANCE_GROUP_NAME",  "targetSize":SIZE,  "versions": [    {      "instanceTemplate": "global/instanceTemplates/INSTANCE_TEMPLATE_NAME"    }  ]}

Replace the following:

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

  • ZONE: the zone in which to create the MIG, which mustbe within the region where the spread placement policy is located.

  • INSTANCE_GROUP_NAME: the name of the MIG to create.

  • SIZE: the size of the MIG.

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

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

Apply the policy to an existing MIG

You can only apply a spread placement policy to an existing MIG if the MIG islocated in the same region as the placement policy or, for zonal MIGs, in a zonewithin the same region as the placement policy.

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

gcloud

To update a MIG to use an instance template that specifies a spreadplacement policy, use thegcloud compute instance-groups managed rolling-action start-update command.

For example, to update a zonal MIG to use an instance template thatspecifies a spread placement policy, and replace the existing VMs from theMIG with new VMs that specify the template's properties, run the followingcommand:

gcloud compute instance-groups managed rolling-action start-updateINSTANCE_GROUP_NAME \    --version=template=INSTANCE_TEMPLATE_NAME \    --zone=ZONE

Replace the following:

  • INSTANCE_GROUP_NAME: the name of an existing MIG.

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

  • ZONE: the zone where the MIG is located. You canonly apply the spread placement policy to a MIG located within the sameregion as the placement policy.

REST

To update a MIG to use an instance template that specifies a spreadplacement policy, and automatically apply the properties of the template andthe placement policy to existing VMs in the MIG, make aPATCH request toone of the following methods:

For example, to update a zonal MIG to use a global instance template thatspecifies a spread placement policy, and replace the existing VMs from theMIG with new VMs that specify the template's properties, make the followingPATCH request:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/INSTANCE_GROUP_NAME{  "instanceTemplate": "global/instanceTemplates/INSTANCE_TEMPLATE_NAME"}

Replace the following:

  • PROJECT_ID: the ID of the project you used to createan existing MIG, the spread placement policy, and the instance templatethat specifies the spread placement policy.

  • ZONE: the zone where the MIG is located. You canonly apply the spread placement policy to a MIG located within the sameregion as the placement policy.

  • INSTANCE_GROUP_NAME: the name of an existing MIG.

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

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

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.