This document describes how to improve the reliability of your virtual machine (VM) instances by creating and applying spread placement policies to them.
A spread placement policy specifies that your VMs should be distributed across different availability domains. This distribution helps mitigate location-specific disruptions, such as hardware errors, and is useful when running large-scale, distributed, and replicated workloads like Hadoop Distributed File System (HDFS), Cassandra, or Kafka.
Before you begin
-
If you haven't already, then 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 by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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 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 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 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
Unless you want to test the application of the spread placement policy to your VMs, Google Cloud recommends creating spread placement policies with two or more availability domains. This mitigates the risk of all VMs being impacted by a single hardware error. For more information, see About spread placement policies.
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.DOMAIN_COUNT
: the distinct number of availability domains to place your VMs in. The value must be between1
and8
.REGION
: the region in which to create the placement 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 in which to create the placement policy.REGION
: the region in which to create the placement policy.POLICY_NAME
: the name of the spread placement policy.DOMAIN_COUNT
: the distinct number of availability domains 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 when creating VMs, instance templates, or MIGs.
To apply a spread placement policy to a Compute Engine resource, select one of the following methods:
- Apply the policy to an existing VM.
- Apply the policy while creating a VM.
- Apply the policy while creating VMs in bulk.
- Apply the policy while creating an instance template.
- Apply the policy to VMs in a MIG.
After you apply a spread placement policy to a VM, you can verify the
availability domain in which the VM is located by
viewing the details of the VM and
checking the value of the availabilityDomain
field.
Apply the policy to an existing VM
Before applying a spread placement policy to an existing VM, consider the following:
If your spread placement policy specifies multiple availability domains, then you can apply the policy to a VM without stopping the VM. However, the VM might need to be relocated to a different availability domain. During this process, Compute Engine stops or live migrates the VM based on its host 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 region
us-central1
, then the VM must be located in a zone inus-central1
. If you need to migrate a VM to another region, then see Move a VM between zones or regions.
If you want to specify the availability domain in which to place your VM, then
apply the placement policy to the VM by
updating its properties.
When updating the VM's properties, make sure to include the resourcePolicies
and scheduling.availabilityDomain
fields.
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.
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 is located.
REST
To apply a spread placement policy to an existing VM, make a POST
request
to the
instances.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 spread placement 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 policy is located.POLICY_NAME
: the name of an existing spread placement policy.
Apply the policy while creating a VM
You can only create a VM that specifies a spread placement policy in 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 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 create VM_NAME \
--availability-domain=DOMAIN_NUMBER \
--machine-type=MACHINE_TYPE \
--resource-policies=POLICY_NAME \
--zone=ZONE
Replace DOMAIN_NUMBER
with the number of the availability
domain to place your VM in. The value must be between 1
and the number of
domains specified in the spread placement policy. To verify the number of
domains in a spread placement policy,
view the details of the placement policy.
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",
"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 spread placement policy is located.ZONE
: the zone where to create the VM in and where the machine type is located. You can only specify a zone within region of 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 the image—for example,debian-cloud
. For more information about the supported image projects, see Public images.IMAGE
: specify one of the following:A specific version of the OS image—for example,
debian-12-bookworm-v20240617
.An image family, which must be formatted as
family/IMAGE_FAMILY
. This specifies the most recent, non-deprecated OS image. For example, if you specifyfamily/debian-12
, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.
REGION
: the region where the spread placement policy is located.POLICY_NAME
: the name of an existing spread placement policy.
Optionally, to specify the availability domain in which to create the VM,
include the availabilityDomain
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
}
}
Replace DOMAIN_NUMBER
with the number of the availability
domain to place your VM in. The value must be between 1
and the number of
domains specified in the spread placement policy. To verify the number of
domains in a spread placement policy,
view the details of the placement policy.
For more information about the configuration options to create a VM, see Create 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 of the following:
You can only create VMs in bulk that specify a spread placement policy in the same region as the placement policy.
When creating VMs in bulk with a spread placement policy, you can optionally specify the availability domain in which to create your VMs. Avoid creating all your VMs in a single domain. Otherwise, you don't mitigate the risk of a single hardware error impacting all your VMs.
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 replace a sequence of numbers in a VM name, use a sequence of hash (#
) characters. For example, usingvm-#
for the name pattern generates VMs with names starting withvm-1
,vm-2
, and continuing up to the number of VMs specified byCOUNT
.POLICY_NAME
: the name of an existing spread placement policy.ZONE
: the zone in which to create the VMs in bulk.
Optionally, to specify the availability domain in which to create the VMs in
bulk, 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
Replace DOMAIN_NUMBER
with the number of the availability
domain to place your VM in. The value must be between 1
and the number of
domains specified in the spread placement policy. To verify the number of
domains 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 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 a POST
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 spread placement 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. To replace a sequence of numbers in a VM name, use a sequence of hash (#
) characters. For example, usingvm-#
for the name pattern generates VMs with names starting withvm-1
,vm-2
, and continuing up to the number of VMs specified byCOUNT
.MACHINE_TYPE
: the machine type for the VMs.IMAGE_PROJECT
: the image project that contains the image—for example,debian-cloud
. For more information about the supported image projects, see Public images.IMAGE
: specify one of the following:A specific version of the OS image—for example,
debian-12-bookworm-v20240617
.An image family, which must be formatted as
family/IMAGE_FAMILY
. This specifies the most recent, non-deprecated OS image. For example, if you specifyfamily/debian-12
, the latest version in the Debian 12 image family is used. For more information about using image families, see Image families best practices.
POLICY_NAME
: the name of an existing spread placement policy.
Optionally, to specify the availability domain in which to create the VMs in
bulk, include the availabilityDomain
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
}
}
}
Replace DOMAIN_NUMBER
with the number of the availability
domain to place your VM in. The value must be between 1
and the number of
domains specified in the spread placement policy. To verify the number of
domains in a spread placement policy,
view the details of the placement policy.
For more information about the configuration options to create VMs in bulk, see Create 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 template in the same region as the spread placement policy. Otherwise, creating the instance template fails.
When creating an instance template, you can optionally specify the availability domain in which to create VMs. Avoid creating all your VMs in a single domain. Otherwise, you don't mitigate the risk of a single hardware error 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, 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.
Optionally, to specify the availability domain in which to create the VMs,
include the --availability-domain
flag.
gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
--availability-domain=DOMAIN_NUMBER \
--machine-type=MACHINE_TYPE \
--resource-policies=POLICY_NAME
Replace DOMAIN_NUMBER
with the number of the availability
domain to create your VMs in. The value must be between 1
and the number
of domains specified in the placement policy. To verify the number of
domains 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 a POST
request to one of the following methods:
To create a global instance template:
instanceTemplates.insert
method.To create a regional instance template:
regionInstanceTemplates.insert
method.
In the request body, specify the resourcePolicies
field.
For example, to create a global instance template that specifies a spread
placement policy, make a POST
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 spread placement policy is located.INSTANCE_TEMPLATE_NAME
: the name of the instance template.IMAGE_PROJECT
: the image project that contains the image—for example,debian-cloud
. For more information about the supported image projects, see Public images.IMAGE
: specify one of the following:A specific version of the OS image—for example,
debian-12-bookworm-v20240617
.An image family, which must be formatted as
family/IMAGE_FAMILY
. This specifies the most recent, non-deprecated OS image. For example, if you specifyfamily/debian-12
, the latest version in the Debian 12 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.POLICY_NAME
: the name of an existing spread placement policy.
Optionally, to specify the availability domain in which to create the VMs,
include the availabilityDomain
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
}
}
}
Replace DOMAIN_NUMBER
with the number of the availability
domain to create your VMs in. The value must be between 1
and the number
of domains specified in the placement policy. To verify the number of
domains in a spread placement policy,
view the details of the placement policy.
For more information about the configuration options to create an instance template, see Create instance templates.
Apply the policy to 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:
Apply the policy while creating a MIG
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 zonal MIG using a global instance template that specifies a spread placement policy, run the following command:
gcloud compute instance-groups managed create INSTANCE_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 existing global instance template that specifies a spread placement policy.ZONE
: the zone in which to create the MIG, which must be within the region where the spread placement policy is located.
REST
To create a MIG using an instance template that specifies a spread placement
policy, make a POST
request to one of the following methods:
To create a zonal MIG:
instanceGroupManagers.insert
method.To create a regional MIG:
regionInstanceGroupManagers.insert
method.
For example, to create a zonal MIG using a global instance template that
specifies a spread placement policy, make a POST
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 spread placement policy and the instance template that specifies the placement policy are located.ZONE
: the zone in which to create the MIG, which must be 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 existing global instance template that specifies a spread placement policy.
For more information about the configuration options to create MIGs, see Basic scenarios for creating MIGs.
Apply the 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 zonal 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 INSTANCE_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 existing global instance template that specifies a spread placement policy.ZONE
: the zone where the MIG is located. You can only apply the spread placement policy to a MIG located within the same region as the 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
one of the following methods:
To update a zonal MIG:
instanceGroupManagers.insert
method.To update a regional MIG:
regionInstanceGroupManagers.insert
method.
For example, to update a zonal MIG to use a global 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/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 create an existing MIG, the spread placement policy, and the instance template that specifies the spread placement policy.ZONE
: the zone where the MIG is located. You can only apply the spread placement policy to a MIG located within the same region as the placement policy.INSTANCE_GROUP_NAME
: the name of an existing MIG.INSTANCE_TEMPLATE_NAME
: the name of an existing global 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?
Learn how to view placement policies.
Learn how to replace, remove, or delete placement policies.
Learn how to do the following with a VM that specifies a placement policy:
Learn more about the live migration process during maintenance events.