Reduce latency by using compact placement policies

---

This document explains how to reduce network latency among your virtual machine (VM) instances by creating and applying compact placement policies to them.

A compact placement policy specifies that your VMs should be physically placed closer to each other. This can help improve performance and reduce network latency among your VMs when, for example, you run high-performance computing (HPC), machine learning (ML), or database server workloads.

You can apply a compact placement policy when you do the following:

• Create or update a VM.
• Create a single-project reservation.
• Create VMs in bulk.
• Create an instance template. The instance template then applies the compact placement policy when you use it to do the following:
  • Create a VM.
  • Create or update a managed instance group (MIG).
  • Create a single-project reservation.

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

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. 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

Required roles

To get the permissions that you need to create and apply a compact 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 compact 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 compact 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
• To view the details of a VM: compute.instances.get 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, compact placement policies have the following restrictions:

• For compact placement policies, you can use max-distance (Preview) to better control how far apart to place your VMs. The following table outlines the supported number of VMs and host maintenance policy for each max-distance value:

  max-distance value	Description	Maximum number of VMs	Supported host maintenance policy
  Unspecified	Based on availability, the VMs are placed as close to each other as possible.	1,500	Migrate or Terminate
  3	The VMs are placed in adjacent clusters for low latency.	1,500	Migrate or Terminate
  2	The VMs are placed in adjacent racks and experience lower network latency than VMs placed in adjacent clusters.	150	Terminate
  1	The VMs are placed in the same rack and minimize network latency as much as possible.	22	Terminate

  Note: The actual maximum number of VMs might be smaller, depending on the available resources for VM placement.

• You can only apply a compact placement policy to A2, A3, C2, C3, C2D, C3D, G2, H3, N2, and N2D machine series. If you use max-distance when creating a compact placement policy, you can't apply the policy to A3, G2, N2, and N2D machine series.

• You can't apply compact placement policies to VMs that specify sole-tenant nodes.

• If you want to create a compact placement policy for a reservation, see the additional requirements for reservations.

Create a compact placement policy

To create a compact placement policy, use one of the following methods:

• Recommended: Without a fixed count.

  You can apply a compact placement policy that doesn't specify a fixed count of VMs to an unspecified number of VMs. This makes the compact placement policy effective no matter the number of VMs you apply it to.

• With a fixed count.

  You can apply a compact placement policy that specifies a fixed count of VMs only to an exact number of VMs. This makes the compact placement policy effective only if it's applied to the specified number of VMs.

Without a fixed count

You can create a compact placement policy using the gcloud CLI and REST.

gcloud

To create a compact placement policy, use the gcloud compute resource-policies create group-placement command with the --collocation=collocated flag.

gcloud compute resource-policies create group-placement POLICY_NAME \
    --collocation=collocated \
    --region=REGION

Replace the following:

• POLICY_NAME: the name of the policy to create.

• REGION: the region where to create the policy. If you want to apply the compact placement policy to existing VMs, create the policy in a region that contains the zone where the VMs are located.

Optionally, for better control over how far apart the VMs are placed when you have strict network latency requirements, you can create a compact placement policy using the gcloud beta compute resource-policies create group-placement command with the --collocation=collocated and --max-distance flags.

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

gcloud beta compute resource-policies create group-placement POLICY_NAME \
    --collocation=collocated \
    --max-distance=MAX_DISTANCE \
    --region=REGION

Replace MAX_DISTANCE with the maximum distance configuration for your VMs. The value must be between 1, which specifies to place your VMs in the same rack for the lowest network latency possible, and 3, which specifies to place your VMs in adjacent clusters. Depending on the machine type and zone specified in the VMs that you apply a compact placement policy to, the following conditions apply:

• If a zone has capacity available, a compact placement policy with a higher maxDistance value (such as 3) might cause your VMs to be placed closer to each other.

• If a zone lacks capacity, a compact placement policy with a lower maxDistance value (such as 1) is more likely to cause the application of the policy to one or more of your VMs to fail.

REST

To create a compact placement policy, make a POST request to the resourcePolicies.insert method. In the request body, include the collocation field and set it to COLLOCATED.

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

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

Replace the following:

• PROJECT_ID: the ID of the project where you want to create the placement policy.

• REGION: the region where to create the placement policy. If you want to apply the compact placement policy to existing VMs, create the policy in a region that contains the zone where the VMs are located.

• POLICY_NAME: the name of the compact placement policy to create.

Optionally, for better control over how far apart the VMs are placed when you have strict network latency requirements, you can create a compact placement policy by making a POST request to the beta.resourcePolicies.insert method. In the request body, include the collocation field set to COLLOCATED, and the maxDistance field.

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

{
  "name": "POLICY_NAME",
  "groupPlacementPolicy": {
    "collocation": "COLLOCATED",
    "maxDistance": "MAX_DISTANCE"
  }
}

Replace MAX_DISTANCE with the maximum distance configuration for your VMs. The value must be between 1, which specifies to place your VMs in the same rack for the lowest network latency possible, and 3, which specifies to place your VMs in adjacent clusters. Depending on the machine type and zone specified in the VMs that you apply a compact placement policy to, the following conditions apply:

• If a zone has capacity available, a compact placement policy with a higher maxDistance value (such as 3) might cause your VMs to be placed closer to each other.

• If a zone lacks capacity, a compact placement policy with a lower maxDistance value (such as 1) is more likely to cause the application of the policy to one or more of your VMs to fail.

With a fixed count

You can create a compact placement policy that specifies a fixed count of VMs using the gcloud CLI and REST.

gcloud

To create a compact placement policy that specifies a fixed count of VMs, use the gcloud compute resource-policies create group-placement command with the --collocation=collocated and --vm-count flags.

gcloud compute resource-policies create group-placement POLICY_NAME \
    --collocation=collocated \
    --region=REGION \
    --vm-count=VM_COUNT

Replace the following:

• POLICY_NAME: the name of the policy to create.

• REGION: the region where to create the policy. If you want to apply the compact placement policy to existing VMs, create the policy in a region that contains the zone where the VMs are located.

• VM_COUNT: the exact number of VMs that you can apply the compact placement policy to. The value must be between 1 and the maximum number of VMs you can apply the compact placement policy to.

Optionally, for better control over how far apart the VMs are placed when you have strict network latency requirements, you can create a compact placement policy using the gcloud beta compute resource-policies create group-placement command with the --collocation=collocated, --max-distance, and --vm-count flags.

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

gcloud beta compute resource-policies create group-placement POLICY_NAME \
    --collocation=collocated \
    --max-distance=MAX_DISTANCE \
    --region=REGION \
    --vm-count=VM_COUNT

Replace MAX_DISTANCE with the maximum distance configuration for your VMs. The value must be between 1, which specifies to place your VMs in the same rack for the lowest network latency possible, and 3, which specifies to place your VMs in adjacent clusters. Depending on the machine type and zone specified in the VMs that you apply a compact placement policy to, the following conditions apply:

• If a zone has capacity available, a compact placement policy with a higher maxDistance value (such as 3) might cause your VMs to be placed closer to each other.

• If a zone lacks capacity, a compact placement policy with a lower maxDistance value (such as 1) is more likely to cause the application of the policy to one or more of your VMs to fail.

REST

To create a compact placement policy that specifies a fixed count of VMs, make a POST request to the resourcePolicies.insert method. In the request body, include the collocation field set to COLLOCATED, and the vmCount field.

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

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

Replace the following:

• PROJECT_ID: the ID of the project where you want to create the placement policy.

• REGION: the region where to create the placement policy. If you want to apply the compact placement policy to existing VMs, create the policy in a region that contains the zone where the VMs are located.

• POLICY_NAME: the name of the compact placement policy to create.

• VM_COUNT: the exact number of VMs that you can apply the compact placement policy to. The value must be between 1 and the maximum number of VMs you can apply the compact placement policy to.

Optionally, for better control over how far apart the VMs are placed when you have strict network latency requirements, you can create a compact placement policy by making a POST request to the beta.resourcePolicies.insert method. In the request body, include the collocation field set to COLLOCATED, the maxDistance field, and the vmCount field.

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

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

Replace MAX_DISTANCE with the maximum distance configuration for your VMs. The value must be between 1, which specifies to place your VMs in the same rack for the lowest network latency possible, and 3, which specifies to place your VMs in adjacent clusters. Depending on the machine type and zone specified in the VMs that you apply a compact placement policy to, the following conditions apply:

• If a zone has capacity available, a compact placement policy with a higher maxDistance value (such as 3) might cause your VMs to be placed closer to each other.

• If a zone lacks capacity, a compact placement policy with a lower maxDistance value (such as 1) is more likely to cause the application of the policy to one or more of your VMs to fail.

Apply compact placement policies

You can apply a compact placement policy to an existing VM, or when you create VMs, instance templates, MIGs, or reservations of VMs.

To create a Compute Engine resource that specifies a compact placement policy, select one of the following methods:

• Apply a compact placement policy to an existing VM.
• Create a VM that specifies a compact placement policy.
• Create VMs in bulk that specify a compact placement policy.
• Create an instance template that specifies a compact placement policy.
• Apply a compact placement policy to the VMs in a MIG.

If you want to specify a compact placement policy when creating a single-project reservation by specifying properties directly, see Create a reservation for a single project instead.

After a compact placement policy is applied to a VM, you can verify the physical location of a VM in relation to other VMs that specify the same policy.

Apply a compact placement policy to an existing VM

You can apply a compact placement policy to an existing VM using the gcloud CLI and REST.

Before applying a compact placement policy to an existing VM, make sure of the following:

• The VM and the compact placement policy are located in the same project.

• The VM is located within the region where the compact placement policy exists.

• The VM specifies a supported machine series and host maintenance policy.

Otherwise, applying the compact placement policy to an existing VM fails.

gcloud

To apply a compact 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 compact placement policy.

• ZONE: the zone where the VM is located.

REST

To apply a compact placement policy to an existing VM, make a POST request to the instances.addResourcePolicies method with 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 compact placement policy and the VM are located.

• ZONE: the zone where the VM exists, which must be within the region where the compact placement policy is located.

• VM_NAME: the name of an existing VM.

• REGION: the region where the compact placement policy is located.

• POLICY_NAME: the name of an existing compact placement policy.

Create a VM that specifies a compact placement policy

You can create a VM that specifies an existing compact placement policy using the gcloud CLI and REST.

gcloud

To create a VM that specifies a compact placement policy, use the gcloud compute instances create command with the --resource-policies flag.

For example, to create a VM that specifies a c2d-standard-2 machine type, run the following command:

gcloud compute instances create VM_NAME \
    --machine-type=c2d-standard-2 \
    --maintenance-policy=MAINTENANCE_POLICY \
    --resource-policies=POLICY_NAME \
    --zone=ZONE

Replace the following:

• VM_NAME: the name of the VM to create.

• MAINTENANCE_POLICY: the host maintenance policy of the VM. If the compact placement policy you specify uses a max-distance value of 1 or 2, you can only specify TERMINATE. Otherwise, you can specify either MIGRATE or TERMINATE.

• POLICY_NAME: the name of an existing compact placement policy.

• ZONE: the zone where to create the VM. You can only create a VM in a zone that is within the region of the compact placement policy you specify.

REST

To create a VM that specifies a compact placement policy, make a POST request to the instances.insert method with the resourcePolicies field.

For example, to create a VM that specifies a c2d-standard-2 machine type, make the following POST request:

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

{
  "machineType": "zones/ZONE/machineTypes/c2d-standard-2",
  "name": "VM_NAME",
  "resourcePolicies": [
    "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
  ],
  "scheduling": {
    "onHostMaintenance": "MAINTENANCE_POLICY"
  }
}

Replace the following:

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

• ZONE: the zone where to create the VM and where the machine type is located. You can only create a VM in a zone that is within the region of the compact placement policy you specify.

• VM_NAME: the name of the VM to create.

• REGION: the region where the compact placement policy is located.

• POLICY_NAME: the name of an existing compact placement policy.

• MAINTENANCE_POLICY: the host maintenance policy of the VM. If the compact placement policy you specify uses a max-distance value of 1 or 2, you can only specify TERMINATE. Otherwise, you can specify either MIGRATE or TERMINATE.

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 compact placement policy

You can create VMs in bulk that specify an existing compact placement policy using the gcloud CLI and REST.

gcloud

To create VMs in bulk that specify a compact placement policy, use the gcloud compute instances bulk create command with the --resource-policies flag.

For example, to create VMs in bulk that all specify a c2d-standard-2 machine type and the same compact placement policy, run the following command:

gcloud compute instances bulk create \
    --async \
    --count=COUNT \
    --machine-type=c2d-standard-2 \
    --maintenance-policy=MAINTENANCE_POLICY \
    --name-pattern=NAME_PATTERN \
    --resource-policies=POLICY_NAME \
    --zone=ZONE

Replace the following:

• COUNT: the number of VMs to create.

• MAINTENANCE_POLICY: the host maintenance policy of the VM. If the compact placement policy you specify uses a max-distance value of 1 or 2, you can only specify TERMINATE. Otherwise, you can specify either MIGRATE or TERMINATE.

• NAME_PATTERN: the name pattern for the VMs to create. Use the hash character (#) to replace it with a sequence of numbers. For example, specifying vm-# creates VMs with names vm-1, vm-2, and so on, up to the number of VMs specified in COUNT.

• POLICY_NAME: the name of an existing compact 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 compact placement policy you specify.

REST

To create VMs in bulk that specify a compact placement policy, make a POST request to the instances.bulkInsert method with the resourcePolicies field.

For example, to create VMs in bulk that all specify a c2d-standard-2 machine type and the same compact placement policy, make the following POST request:

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

{
  "count": "COUNT",
  "machineType": "zones/ZONE/machineTypes/c2d-standard-2",
  "namePattern": "NAME_PATTERN",
  "instanceProperties": {
    "resourcePolicies": [
      "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
    ],
    "scheduling": {
      "onHostMaintenance": "MAINTENANCE_POLICY"
    }
  }
}

Replace the following:

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

• ZONE: the zone where to bulk create the VMs and where the machine type is located. You can only create VMs in zones that are within the region of the compact 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, specifying vm-# creates VMs with names vm-1, vm-2, and so on, up to the number of VMs specified in COUNT.

• REGION: the region where the compact placement policy is located.

• POLICY_NAME: the name of an existing compact placement policy.

• MAINTENANCE_POLICY: the host maintenance policy of the VM. If the compact placement policy you specify uses a max-distance value of 1 or 2, you can only specify TERMINATE. Otherwise, you can specify either MIGRATE or TERMINATE.

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 compact placement policy

You can create an instance template that specifies an existing compact placement policy using the gcloud CLI and REST.

After you create an instance template, you can use it to do the following:

• Apply a compact placement policy to VMs in a MIG.

• Create a VM from an instance template.

• Create a reservation for a single project.

Caution: Placement policies are regional resources. If you specify a placement policy when creating an instance template, the policy restricts the use of the template to the region where it is located. For example, if you create a compact placement policy in region us-central1 and include the policy in an instance template, you can only use the template to create MIGs, VMs, or reservations of VMs within the same region. Otherwise, you encounter errors.

gcloud

To create an instance template that specifies a compact 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 c2d-standard-2 machine type and an existing compact placement policy, run the following command:

gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
    --machine-type=c2d-standard-2 \
    --maintenance-policy=MAINTENANCE_POLICY \
    --resource-policies=POLICY_NAME

Replace the following:

• INSTANCE_TEMPLATE_NAME: the name of the instance template.

• MAINTENANCE_POLICY: the host maintenance policy of the VM. If the compact placement policy you specify uses a max-distance value of 1 or 2, you can only specify TERMINATE. Otherwise, you can specify either MIGRATE or TERMINATE.

• POLICY_NAME: the name of an existing compact placement policy.

REST

To create an instance template that specifies a compact placement policy, make a POST request to the instanceTemplates.insert method. In the request body, specify the resourcePolicies field.

For example, to create a global instance template that specifies a c2d-standard-2 machine type and an existing compact placement policy, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/instanceTemplates

{
  "name": "INSTANCE_TEMPLATE_NAME",
  "machineType": "zones/ZONE/machineTypes/c2d-standard-2",
  "properties": {
    "resourcePolicies": {
      "POLICY_NAME"
    },
    "scheduling": {
      "onHostMaintenance": "MAINTENANCE_POLICY"
    }
  }
}

Replace the following:

• PROJECT_ID: the ID of the project where the compact placement policy you want to apply to the instance template is located.

• ZONE: the zone where the machine type is located.

• INSTANCE_TEMPLATE_NAME: the name of the instance template.

• POLICY_NAME: the name of an existing compact placement policy.

• MAINTENANCE_POLICY: the host maintenance policy of the VM. If the compact placement policy you specify uses a max-distance value of 1 or 2, you can only specify TERMINATE. Otherwise, you can specify either MIGRATE or TERMINATE.

For more information about the configuration options to create an instance template, see Create instance templates.

Apply a compact placement policy to the VMs in a MIG

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

• Create a MIG that specifies the same compact placement policy.

• Apply the compact placement policy to an existing MIG.

If you want to apply a compact 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 reservations, quotas, and hardware requirements.

Note: If you want to apply the same compact placement policies to multiple MIGs, the placement policy restricts the total number of VMs you can apply the policy to. To overcome this limitation, create separate instance templates that each specify a compact placement policy with duplicate properties, and then use one template per MIG only.

Create a MIG that specifies a compact placement policy

You can create a MIG using an instance template that specifies a compact placement policy using the gcloud CLI and REST.

gcloud

To create a MIG using an instance template that specifies a compact placement policy, use the gcloud compute instance-groups managed create command with the --template flag.

For example, to create a regional MIG with an 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 compact placement policy is located.

• SIZE: the size of the MIG.

• INSTANCE_TEMPLATE_NAME: the name of an existing instance template that specifies a compact placement policy.

REST

To create a MIG using an instance template that specifies a compact placement policy, make a POST request to the instanceGroupManagers.insert or regionInstanceGroupManagers.insert methods with the instanceTemplate field 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, 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",
  "distributionPolicy": {
    "targetShape": "ANY_SINGLE_ZONE"
  },
  "targetSize": SIZE
}

Replace the following:

• PROJECT_ID: the ID of the project where the compact 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 compact 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 compact 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 compact placement policy to an existing MIG

You can apply a compact 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 compact placement policy, use the gcloud compute instance-groups managed rolling-action start-update command with the --version=template flag.

For example, to update a regional MIG to use an instance template that specifies a compact 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 compact placement policy to a MIG that is in the same region.

• INSTANCE_TEMPLATE_NAME: the name of an existing instance template that specifies a compact placement policy.

REST

To update a MIG to use an instance template that specifies a compact 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 with the instanceTemplate field.

For example, to update a regional MIG to use an instance template that specifies a compact 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 where the MIG, the compact placement policy, and the instance template that specifies the placement policy are located.

• REGION: the region where the MIG is located. You can only apply the compact 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 compact 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.

Verify the physical location of a VM

After you apply a compact placement policy to a VM, you can view how the compact placement policy affected its physical location in relation to other VMs that specify the same policy. This helps you determine if the compact placement policy was correctly applied to a VM and map which VMs are the closest to each other.

You can verify the physical location of a VM that specifies a placement policy using the gcloud CLI and REST.

gcloud

To view the physical location of a VM that specifies a compact placement policy, use the gcloud compute instances describe command with the --format flag.

gcloud compute instances describe VM_NAME \
    --format="table[box,title=VM-Position](resourcePolicies.scope():sort=1,resourceStatus.physicalHost:label=location)" \
    --zone=ZONE

Replace the following:

• VM_NAME: the name of an existing VM.

• ZONE: the zone where the VM is located.

The output is similar to the following:

VM-Position

RESOURCE_POLICIES: us-central1/resourcePolicies/example-policy']
PHYSICAL_HOST: /CCCCCCC/BBBBBB/AAAA

The value for the PHYSICAL_HOST field is composed by three parts. These parts each represent the cluster, rack, and host where the VM is located.

When comparing the position of two VMs that specify the same compact placement policy, the more parts in the PHYSICAL_HOST field the VMs share, the closer they are located to each other. For example, if two VMs both specify one of the following sample values for the PHYSICAL_HOST field:

• /CCCCCCC/xxxxxx/xxxx: the two VMs are placed in the same cluster, which equals a max-distance value of 2. VMs placed in the same cluster experience low network latency.

• /CCCCCCC/BBBBBB/xxxx: the two VMs are placed in the same rack, which equals a max-distance value of 1. VMs placed in the same rack experience lower network latency than VMs placed in the same cluster.

• /CCCCCCC/BBBBBB/AAAA: the two VMs share the same host. VMs placed in the same host minimize network latency as much as possible.

REST

To view the physical location of a VM that specifies a compact placement policy, make a GET request to the instances.get method.

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

Replace the following:

• PROJECT_ID: the ID of the project where the VM is located.

• ZONE: the zone where the VM is located.

• VM_NAME: the name of an existing VM that specifies a placement policy.

The output is similar to the following:

{
...
"resourcePolicies": [
  "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-policy"
],
"resourceStatus": {
  "physicalHost": "/xxxxxxxx/xxxxxx/xxxxx"
},
...
}

The value for the physicalHost field is composed by three parts. These parts each represent the cluster, rack, and host where the VM is located.

When comparing the position of two VMs that specify the same compact placement policy, the more parts in the physicalHost field the VMs share, the closer they are located to each other. For example, if two VMs both specify one of the following sample values for the physicalHost field:

• /CCCCCCC/xxxxxx/xxxx: the two VMs are placed in the same cluster, which equals a max-distance value of 2. VMs placed in the same cluster experience low network latency.

• /CCCCCCC/BBBBBB/xxxx: the two VMs are placed in the same rack, which equals a max-distance value of 1. VMs placed in the same rack experience lower network latency than VMs placed in the same cluster.

• /CCCCCCC/BBBBBB/AAAA: the two VMs share the same host. VMs placed in the same host minimize network latency as much as possible.

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:

  • View the status of the VM.

  • Connect to the VM.