Defining instance placement policies

You can control where your virtual machine (VM) instances are physically located relative to each other within a zone. The following placement policies are available:

  • Spread placement policies. Use spread policies when you want VMs spread out from each other to reduce the impact of host system failures.
  • Compact placement policies. Use compact policies when you want VMs to be located close to each other for low network latency between the VMs.

Before you begin

Support and restrictions

Placement policies have the following support and restrictions:

  • Spread placement policies:
    • Support up to 8 VMs per policy.
    • Apply to a dynamic number of VMs.
    • Support only N1, N2, N2D, and C2 machine types.
    • Support live migration.
  • Compact placement policies:
    • Support up to 22 VMs in each policy.
    • Apply to a fixed number of VMs.
    • Support only C2 machine types.
    • Don't support live migration.
    • Apply to VMs that are set to TERMINATE for host maintenance events.
    • Can't be applied to existing VMs.
  • Both spread and compact placement policies:

Create a placement policy

To control where your VMs are located relative to one another, use the following process:

  1. Create either a spread or compact placement policy with the placement configuration that your VMs need.
    • Spread placement policies strictly place your VM instances across the underlying datacenter infrastructure so that the VMs don't share the same host or power system. This approach reduces the impact of host or power failures.
    • Compact placement policies put your VM instances close together for low network latency between the VMs.
  2. Apply the placement policy to one or more instances. VMs that share the same policy are placed relative to each other based on how you defined the policy.

Create a spread placement policy

To create a spread placement policy where instances are located across several distinct availability domains, specify the number of availability domains that this policy should use to separate instances from each other.

gcloud

Use the gcloud tool to create the policy.

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

Replace the following:

  • POLICY_NAME: the name for the new policy
  • DOMAIN_COUNT: the number of distinct sets of host hardware and physical networks that this policy will use to separate VMs
  • REGION: the region where you plan to create VM instances that use this policy
  • PROJECT_ID: your project ID

API

Create a spread placement policy by using the resourcePolicies.insert method in the Cloud Console APIs & services.

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

In the body of the request, provide details of the placement policy:

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

Replace the following:

  • PROJECT_ID: your project ID
  • REGION: the region where you plan to create VM instances that use this policy
  • POLICY_NAME: the name for the new policy
  • DOMAIN_COUNT: the number of distinct sets of host hardware and physical networks that this policy will use to separate instances

Create a compact placement policy

To create a compact placement policy where instances are located closer to each other and on the same network infrastructure, specify a COLLOCATED policy and a number of VM instances that you plan to include in that policy.

gcloud

Use the gcloud tool to create the policy.

gcloud compute resource-policies create group-placement POLICY_NAME \
    --collocation COLLOCATED \
    --vm-count VM_COUNT \
    --region REGION \
    --project PROJECT_ID

Replace the following:

  • POLICY_NAME: the name for the new policy
  • VM_COUNT: the number of VMs to include in that policy

    For compact policies, you must apply the policy to exactly this number of VMs.

  • REGION: the region where you plan to create VM instances that use this policy

  • PROJECT_ID: your project ID

API

Create a spread placement policy using the resourcePolicies.insert method in the Cloud Console APIs & services.

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

In the body of the request, provide details of the placement policy:

{
  "name": "POLICY_NAME",
  "groupPlacementPolicy": {
    "vmCount": VM_COUNT,
    "collocation": "COLLOCATED"
  }
}

Replace the following:

  • PROJECT_ID: your project ID
  • REGION: the region where you plan to create VM instances that use this policy
  • POLICY_NAME: the name for the new policy
  • VM_COUNT: the number of VMs to include in that policy

    For compact policies, you must apply the policy to exactly this number of VMs.

Apply placement policies to instances

Use the following procedures to apply placement policies to new and existing instances.

Apply a placement policy to a new instance

After you create the placement policy, apply it to one or more instances. VMs that share the same policy are placed relative to each other based on how you defined the policy.

gcloud

Apply a placement policy to an instance by including the --resource-policies flag when you create a new instance. If you run multiple instances create commands, use the --async flag to prevent the commands from timing out while Compute Engine creates the VMs under the placement policy.

For compact placement policies, you must include the --maintenance-policy=TERMINATE and --no-restart-on-failure flags.

gcloud compute instances create VM_NAME \
    --zone ZONE \
    --resource-policies POLICY_NAME \
    --image-family IMAGE_FAMILY \
    --image-project IMAGE_PROJECT \
    --project PROJECT_ID \
    [--maintenance-policy=TERMINATE] \
    [--no-restart-on-failure] \
    [--async]

Replace the following:

  • VM_NAME: the name for the new VM
  • ZONE: the zone where you want to create the new VM

    This zone must be in the same region where the placement policy is located.

  • POLICY_NAME: the name of the placement policy that you want to apply to this VM

    You can apply more than one placement policy to a VM.

  • IMAGE_FAMILY: one of the available image families

  • IMAGE_PROJECT: the image project to which the image belongs

  • PROJECT_ID: your project ID

API

Apply a placement policy to a VM by including the resourcePolicies property when you create a new VM.

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

In the body of the request, provide the resource policy. For compact placement policies, you must include the "onHostMaintenance": "TERMINATE" and "automaticRestart": false arguments:

{
  "name": "VM_NAME",
  "machineType": "machineTypes/MACHINE_TYPE"
  "networkInterfaces": [{
    "accessConfigs": [{
      "type": "ONE_TO_ONE_NAT",
      "name": "External NAT"
    }],
    "network": "global/networks/default"
  }],
  "scheduling": {
    "onHostMaintenance": "TERMINATE",
    "automaticRestart": false
  },
  "disks": [{
     "autoDelete": "true",
     "boot": "true",
     "type": "PERSISTENT",
     "initializeParams": {
       "sourceImage": "projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY"
     }
  }],
  "resourcePolicies": [
    "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
  ]
}

Replace the following:

  • PROJECT_ID: your project ID
  • ZONE: the zone where you want to create the new VM

    This zone must be in the same region where the placement policy is located.

  • VM_NAME: the name for the new VM

  • MACHINE_TYPE: the machine type of the VM

  • IMAGE_PROJECT: the image project to which the image belongs

  • IMAGE_FAMILY: one of the available image families

  • REGION: the region where you created the placement policy

  • POLICY_NAME: the name of the placement policy that you want to apply to this VM

    You can apply more than one placement policy to a VM.

Apply a placement policy to an existing instance

If you create a spread placement policy, you can apply it to one or more existing VMs without restarting the VM.

gcloud

Apply a spread placement policy to an existing instance by using the add-resource-policies command.

For compact placement policies, you must include the --maintenance-policy=TERMINATE and --no-restart-on-failure flags.

gcloud compute instances add-resource-policies VM_NAME \
    --zone ZONE \
    --resource-policies POLICY_NAME \
    --project PROJECT_ID
    [--maintenance-policy=TERMINATE] \
    [--no-restart-on-failure]

Replace the following:

  • VM_NAME: the name of the VM
  • ZONE: the zone of the VM

    This zone must be in the same region where the placement policy is located.

  • POLICY_NAME: the name of the placement policy that you want to apply to this VM

    You can apply more than one placement policy to a VM.

  • PROJECT_ID: your project ID

API

Apply a spread placement policy to an existing instance by using the addResourcePolicies method.

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

In the body of the request, provide the resource policy. For compact placement policies, you must include the "onHostMaintenance": "TERMINATE" and "automaticRestart": false arguments.

{
  "resourcePolicies": [
    "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
  ]
   "scheduling": {
    "onHostMaintenance": "TERMINATE",
    "automaticRestart": false
  },
}

Replace the following:

  • PROJECT_ID: your project ID
  • ZONE: the zone where you want to create the new VM

    This zone must be in the same region where the placement policy is located.

  • VM_NAME: the name for the new VM

  • REGION: the region where you plan to create VM instances that use this policy

  • POLICY_NAME: the name of the placement policy that you want to apply to this VM

    You can apply more than one placement policy to a VM.

View placement policies

You can view placement policies applied to a VM and details of a specific placement policy by using the gcloud tool and the Compute Engine API.

View the placement policy of a VM

gcloud

To view a VM's resource placement policy, use the gcloud compute instances describe command:

gcloud compute instances describe VM_NAME

Replace VM_NAME with the name of your VM.

If a placement policy is available, the output contains the resourcePolicies field:

resourcePolicies:
https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGIONS/resourcePolicies/POLICY_NAME

API

To view a VM's resource placement policy, use the instances.get method:

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

Replace the following:

  • PROJECT_ID: your project ID
  • ZONE: the zone containing the VM
  • VM_NAME: the name for your VM

If a placement policy is available, the resourcePolicies field returns resource policies of your VM.

"resourcePolicies": [
"https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies/VM_NAME"
],

View details of a placement policy

gcloud

To view details of a placement policy, use the gcloud compute resource-policies describe command:

gcloud compute resource-policies describe POLICY_NAME

Replace POLICY_NAME with the name of the placement policy.

If the placement policy is available, the output contains details of the placement policy:

...
groupPlacementPolicy:
  availabilityDomainCount: 2
kind: compute#resourcePolicy
name: POLICY_NAME
region: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION
...

API

To view details of a placement policy, use the resourcePolicies.get method:

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

Replace the following:

  • PROJECT_ID: your project ID
  • REGION: the region containing the VM
  • POLICY_NAME: the name for the placement policy

If the placement policy is available, the response body contains details of the placement policy:

...
"region": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION",
"name": "POLICY_NAME",
"groupPlacementPolicy": {
  "availabilityDomainCount": 2
},
"kind": "compute#resourcePolicy"
...

What's next?