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.
You can apply a spread placement policy when you do the following:
- Create or update a VM.
- Create VMs in bulk.
- Create an instance template. The instance template then applies the
spread placement policy when you use it to do the following:
- Create a VM.
- Create or update a managed instance group (MIG).
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
-
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 the VM or the 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 an existing VM:
compute.instances.addResourcePolicies
on the project
You might also be able to get these permissions with custom roles or other predefined roles.
Restrictions
In addition to the general restrictions for placement policies, spread placement policies have the following restrictions:
You can only apply a spread placement policy to 8 VMs maximum.
You can't apply spread placement policies to reservations of VMs.
You can't verify the physical location of VMs.
Create a spread placement policy
You can create a spread placement policy using the gcloud CLI and REST.
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 between2
and8
, 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 between2
and8
, 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.
- Create a VM that specifies a spread placement policy.
- Create VMs in bulk that specify a spread placement policy.
- Create an instance template that specifies a spread placement policy.
- Apply a spread placement policy to the VMs in a MIG.
Apply a spread placement policy to an existing VM
You can apply a spread placement policy to an existing VM using the gcloud CLI and REST.
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 that specifies a spread placement policy
You can create a VM that specifies an existing spread placement policy using the gcloud CLI and REST.
gcloud
To create a VM that specifies a spread placement policy, use the
gcloud compute instances create
command
with the --resource-policies
flag.
For example, to create a VM that has default properties and specifies a spread placement policy, run the following command:
gcloud compute instances create VM_NAME \
--resource-policies=POLICY_NAME \
--zone=ZONE
Replace the following:
VM_NAME
: the name of the VM to create.POLICY_NAME
: the name of an existing spread placement policy.ZONE
: the zone where to create the VM. You can only create a VM in a zone that is within the region where the spread placement policy you specify is located.
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.
For example, to create a VM that has default properties and specifies a
spread placement policy, make the following POST
request:
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances
{
"name": "VM_NAME",
"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. You can only create a VM in a zone that is within the region where the spread placement policy you specify is located.VM_NAME
: the name of the VM to create.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 and the IAM roles to create a VM, see Create and start a VM instance.
Create VMs in bulk that specify a spread placement policy
You can create VMs in bulk that specify an existing spread placement policy using the gcloud CLI and REST.
gcloud
To create VMs in bulk that specify a spread placement policy, use the
gcloud compute instances bulk create
command
with the --async
and --resource-policies
flags.
For example, to create VMs in bulk that all have default properties and specify the same spread placement policy, run the following command:
gcloud compute instances bulk create \
--async \
--count=COUNT \
--name-pattern=NAME_PATTERN \
--resource-policies=POLICY_NAME \
--zone=ZONE
Replace the following:
COUNT
: the number of VMs to create.NAME_PATTERN
: the name pattern for the VMs to create. Use the hash character (#
) to replace it with a sequence of numbers. For example, specifyingvm-#
creates VMs with namesvm-1
,vm-2
, and so on, up to the number of VMs specified inCOUNT
.POLICY_NAME
: the name of an existing spread placement policy.ZONE
: the zone where to bulk create the VMs. You can only create VMs in zones that are within the region of the spread placement policy you specify.
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 that all have default properties and
specify the same spread placement policy, make the following POST
request:
POST https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert
{
"count": "COUNT",
"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 bulk create the VMs. You can only create VMs in zones that are within the region of the spread placement policy you specify.COUNT
: the number of VMs to create.NAME_PATTERN
: the name pattern for the VMs to create. Use the hash character (#
) to replace it with a sequence of numbers. For example, specifyingvm-#
for creates VMs with namesvm-1
,vm-2
, and so on, up to the number of VMs specified inCOUNT
.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 or the IAM roles to create VMs in bulk, see Create VMs in bulk.
Create an instance template that specifies a spread placement policy
You can create an instance template that specifies an existing spread placement policy using the gcloud CLI and REST.
After you create an instance template, you can use it to do the following:
gcloud
To create an instance template that specifies a spread placement policy, use
the
gcloud compute instance-templates create
command
with --resource-policies
flag.
For example, to create a global instance template that has default VM properties and includes a spread placement policy, run the following command:
gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
--resource-policies=POLICY_NAME
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.PROJECT_ID
: the ID of the project where the spread placement policy you want to apply to the instance template is located.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 has default VM
properties and 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": {
"resourcePolicies": {
"POLICY_NAME"
}
}
}
Replace the following:
PROJECT_ID
: the ID of the project where the instance template you want to apply the spread placement policy to is located.INSTANCE_TEMPLATE_NAME
: the name of the instance template.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 that specifies a spread placement policy
You can create a MIG using an instance template that specifies a spread placement policy using the gcloud CLI and REST.
gcloud
To create a MIG using an instance template that specifies a spread
placement policy, use the
gcloud compute instance-groups managed create
command
with the --template
flag set to the name of the existing template.
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. In the request body, include the instanceTemplate
field and set
it to the name of the existing template.
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 and the IAM roles to create MIGs, see Basic scenarios for creating MIGs.
Apply a spread placement policy to an existing MIG
You can apply a spread placement policy to an existing MIG using an instance template that specifies the same placement policy using the gcloud CLI and REST.
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 and the IAM roles 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.