Defining instance placement policies

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

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

Before you begin

Restrictions

Placement policies have the following restrictions:

  • Spread:
    • Up to 8 instances per policy
    • Can apply to a dynamic number of instances
    • Support only for N1, N2, N2D, and C2 machine types
  • Compact:
    • Up to 22 instances in each policy
    • Applies to a fixed number of instances
    • Support only for C2 machine types
    • Does not support Live Migration and instances with placement policies must be set to TERMINATE on host maintenance
    • Cannot be applied to existing instances
  • Both spread and compact:

Defining and applying a placement policy

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

  1. Create a placement policy with the placement configuration that your instances need. You can create one of the following policy types:
    • Spread placement policies strictly place your VM instances across the underlying datacenter infrastructure so that the instances do not share the same host or power system. This reduces the impact of host or power failures.
    • Compact placement policies put your VM instances close together for low network latency between the instances.
  2. Apply the placement policy to one or more instances. Instances 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 instances
  • 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

{
  "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 VM instances to include in that policy. For compact policies, you must apply the policy to exactly this number of instances.
  • 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

{
  "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 VM instances to include in that policy. For compact policies you must apply the policy to exactly this number of instances.

Applying placement policies to instances

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

Applying a placement policy to a new instance

After you create the placement policy, apply it to one or more instances. Instances 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. For compact placement policies, you must include --maintenance-policy=TERMINATE --no-restart-on-failure:

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]]

Replace the following:

  • VM_NAME: the name for the new instance.
  • ZONE: the zone where you want to create the new instance. 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 instance. You can apply more than one placement policy to an instance.
  • 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 an instance by including the resourcePolicies property when you create a new instance. For compact placement policies, you must include "onHostMaintenance": "TERMINATE" and "automaticRestart": false:

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

{
  "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 instance. This zone must be in the same region where the placement policy is located.
  • VM_NAME: the name for the new instance.
  • MACHINE_TYPE: the machine type of the instance.
  • 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 instance. You can apply more than one placement policy to an instance.

Applying a placement policy to an existing instance

If you create a spread placement policy, you can apply it to one or more existing instances.

gcloud

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

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

Replace the following:

  • VM_NAME: the name of the instance.
  • ZONE: the zone of the instance. 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 instance. You can apply more than one placement policy to an instance.
  • PROJECT_ID: your project ID.

API

Apply a spread placement policy to an existing instance by using the addResourcePolicies method. Include the --resource-policies flag:

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: your project ID.
  • ZONE: the zone where you want to create the new instance. This zone must be in the same region where the placement policy is located.
  • VM_NAME: the name for the new instance.
  • 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 instance. You can apply more than one placement policy to an instance.

What's next?