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.
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 compact placement policy to VMs, ask your administrator to grant you the following IAM roles on your project:
-
Compute Instance Admin (v1) (
roles/compute.instanceAdmin.v1
) -
To create a reservation:
Compute Admin (
roles/compute.admin
)
For more information about granting roles, see Manage access.
These predefined roles contain 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 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 a reservation:
compute.reservations.create
on the project -
To create an instance template:
compute.instanceTemplates.create
on the project -
To create a regional or zonal managed instance group (MIG):
compute.instanceGroupManagers.create
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.
Create a compact placement policy
When creating a compact placement policy, you can optionally specify one or both of the following:
A maximum distance value. This lets you control the distance among your VMs when you have strict network latency requirements. Depending on the machine type and zone of the VMs you apply the policy to, the following conditions apply:
If a zone has capacity available, then a compact placement policy with a higher maximum distance (such as
3
) might cause your VMs to be placed closer to each other.If a zone lacks capacity, then a compact placement policy with a lower maximum distance (such as
1
) is more likely to prevent the policy from being applied to some VMs.
Additionally, maximum distance values affect the number of VMs you can apply the compact placement policy to, as well as the VMs' host maintenance policy. For more information, see Restrictions for compact placement policies.
A fixed number of VMs. This makes the compact placement policy effective only when you apply it to a specific number of VMs. Attempting to apply the compact placement policy to more VMs than the specified number causes errors. You can't apply compact placement policies with a fixed number of VMs to reservations.
To create a compact placement policy, use the gcloud CLI or 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 an existing VM, create the policy in a region that contains the zone where the VM is located.
Optionally, you can do one or both of the following:
To better control how far apart to place your VMs, use
gcloud beta compute resource-policies create group-placement
command and include the--max-distance
flag.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 between1
, which specifies to place your VMs in the same rack for the lowest network latency possible, and3
, which specifies to place your VMs in adjacent clusters. If you want to apply the compact placement policy to a reservation, then you can't specify a value of1
.To make the compact placement policy effective only when applied to a specific number of VMs, include the
--vm-count
flag.gcloud compute resource-policies create group-placement POLICY_NAME \ --collocation=collocated \ --region=REGION \ --vm-count=VM_COUNT
Replace
VM_COUNT
with the exact number of VMs that you can apply the compact placement policy to. The value must be between1
and the maximum number of VMs you can apply the compact placement policy to.
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 policy. If you want to apply the compact placement policy to an existing VM, create the policy in a region that contains the zone where the VM is located.POLICY_NAME
: the name of the compact placement policy to create.
Optionally, you can do one or both of the following:
To better control how far apart to place your VMs, make a
POST
request to thebeta.resourcePolicies.insert
method. In the request body, include themaxDistance
field.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 between1
, which specifies to place your VMs in the same rack for the lowest network latency possible, and3
, which specifies to place your VMs in adjacent clusters. If you want to apply the compact placement policy to a reservation, then you can't specify a value of1
.To make the compact placement policy effective only when applied to a specific number of VMs, include the
vmCount
field in the request body.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies { "name": "POLICY_NAME", "groupPlacementPolicy": { "collocation": "COLLOCATED", "vmCount": "VM_COUNT" } }
Replace
VM_COUNT
with the exact number of VMs that you can apply the compact placement policy to. The value must be between1
and the maximum number of VMs you can apply the compact placement policy to.
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 with a compact placement policy.
- Create VMs in bulk with a compact placement policy.
- Create a reservation with a compact placement policy.
- Create an instance template with a compact placement policy.
- Apply a compact placement policy to the VMs in a MIG.
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
Before applying a compact placement policy to an existing VM, make sure of the following:
The VM and the compact 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.The VM must use a supported machine series and host maintenance policy. If you need to make changes to the VM, then do one or both of the following:
If you want to apply a compact placement policy that specifies a fixed number of VMs, then you must update the VM to not automatically restart after an host error.
Otherwise, applying the compact placement policy to the VM fails. If the VM already specifies a placement policy and you want to replace it, then see Replace a placement policy in a VM instead.
To apply a compact placement policy to an existing VM, select one of the following options:
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 theinstances.addResourcePolicies
method. In the request body, include theresourcePolicies
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 with a compact placement policy
You can only create a VM with a compact placement policy in a zone within the same region as the placement policy.
To create a VM that specifies a compact placement policy, select one of the following options:
gcloud
To create a VM that specifies a compact placement policy, use the
gcloud compute instances create
command
with the --resource-policies
flag.
gcloud compute instances create VM_NAME \
--machine-type=MACHINE_TYPE \
--maintenance-policy=MAINTENANCE_POLICY \
--resource-policies=POLICY_NAME \
--zone=ZONE
Replace the following:
VM_NAME
: the name of the VM to create.MACHINE_TYPE
: a supported machine type for compact placement policies.MAINTENANCE_POLICY
: the host maintenance policy of the VM. If the compact placement policy you specify uses a maximum distance value of1
or2
, you can only specifyTERMINATE
. Otherwise, you can specify eitherMIGRATE
orTERMINATE
.POLICY_NAME
: the name of an existing compact placement policy. If the compact placement policy specifies a fixed number of VMs, then you must include the--no-restart-on-failure
flag. This indicates that the VM doesn't automatically restart after an host error.ZONE
: the zone where to create the VM.
REST
To create a VM that specifies a compact 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",
"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 specify a machine type that is available within the region of the compact placement policy.VM_NAME
: the name of the VM to create.MACHINE_TYPE
: a supported machine type for compact placement policies.REGION
: the region where the compact placement policy is located.POLICY_NAME
: the name of an existing compact placement policy. If the compact placement policy specifies a fixed number of VMs, then, in thescheduling
field, you must include theautomaticRestart
field set tofalse
. This indicates that the VM doesn't automatically restart after an host error.MAINTENANCE_POLICY
: the host maintenance policy of the VM. If the compact placement policy you specify uses a maximum distance value of1
or2
, you can only specifyTERMINATE
. Otherwise, you can specify eitherMIGRATE
orTERMINATE
.
For more information about the configuration options to create a VM, see Create and start a VM instance.
Create VMs in bulk with a compact placement policy
You can only create VMs in bulk with a compact placement policy in the same region as the placement policy.
To create VMs in bulk that specify a compact placement policy, select one of the following options:
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 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 \
--maintenance-policy=MAINTENANCE_POLICY \
--name-pattern=NAME_PATTERN \
--resource-policies=POLICY_NAME \
--zone=ZONE
Replace the following:
COUNT
: the number of VMs to create, which can't be higher than the supported maximum number of VMs for the specified compact placement policy.MACHINE_TYPE
: a supported machine type for compact placement policies.MAINTENANCE_POLICY
: the host maintenance policy of the VM. If the compact placement policy you specify uses a maximum distance value of1
or2
, you can only specifyTERMINATE
. Otherwise, you can specify eitherMIGRATE
orTERMINATE
.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 compact placement policy. If the compact placement policy specifies a fixed number of VMs, then you must include the--no-restart-on-failure
flag. This indicates that VMs don't automatically restart after an host error.ZONE
: the zone where to create the VMs in bulk.
REST
To create VMs in bulk that specify a compact placement policy, make a POST
request 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://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert
{
"count": "COUNT",
"machineType": "MACHINE_TYPE",
"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 create the VMs in bulk.COUNT
: the number of VMs to create, which can't be higher than the supported maximum number of VMs for the specified compact placement policy.MACHINE_TYPE
: a supported machine type for compact placement policies.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
.REGION
: the region where the compact placement policy is located.POLICY_NAME
: the name of an existing compact placement policy. If the compact placement policy specifies a fixed number of VMs, then, in thescheduling
field, you must include theautomaticRestart
field set tofalse
. This indicates that VMs don't automatically restart after an host error.MAINTENANCE_POLICY
: the host maintenance policy of the VM. If the compact placement policy you specify uses a maximum distance value of1
or2
, you can only specifyTERMINATE
. Otherwise, you can specify eitherMIGRATE
orTERMINATE
.
For more information about the configuration options to create VMs in bulk, see Create VMs in bulk.
Create a reservation with a compact placement policy
If you want to create an on-demand, single-project reservation that specifies a compact placement policy, then you must create a specifically targeted reservation. When you create VMs to consume the reservation, make sure of the following:
The VMs must specify the same compact placement policy applied to the reservation.
The VMs must specifically target the reservation to consume it. For more information, see Consume VMs from a specific reservation.
To create a single-project reservation with a compact placement policy, select one of the following methods:
Create the reservation by specifying properties directly as described in this section.
Create an instance template with a compact placement policy as described in this document, and then create a single-project reservation by specifying the newly created instance template.
To create a single-project reservation with a compact placement policy by specifying properties directly, select one of the following options:
gcloud
To create a single-project reservation with a compact placement policy by
specifying properties directly, use the
gcloud compute reservations create
command
with the --require-specific-reservation
and --resource-policies
flags.
gcloud compute reservations create RESERVATION_NAME \
--machine-type=MACHINE_TYPE \
--require-specific-reservation \
--resource-policies=policy=POLICY_NAME \
--vm-count=NUMBER_OF_VMS \
--zone=ZONE
Replace the following:
RESERVATION_NAME
: the name of the reservation.MACHINE_TYPE
: a supported machine type for compact placement policies.POLICY_NAME
: the name of an existing compact placement policy. You can't specify a compact placement policy with a fixed number of VMs. Otherwise, creating the reservation fails.NUMBER_OF_VMS
: the number of VMs to reserve, which can't be higher than the supported maximum number of VMs for the specified compact placement policy.ZONE
: the zone where to reserve VMs. You can only reserve VMs in a zone within the region of the specified compact placement policy.
REST
To create a single-project reservation with a compact placement policy by
specifying properties directly, make a POST
request to the
reservations.insert
method.
In the request body, include the resourcePolicies
field, and the
specificReservationRequired
field set to true
.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations
{
"name": "RESERVATION_NAME",
"resourcePolicies": {
"policy" : "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
},
"specificReservation": {
"count": "NUMBER_OF_VMS",
"instanceProperties": {
"machineType": "MACHINE_TYPE",
}
},
"specificReservationRequired": true
}
Replace the following:
PROJECT_ID
: the ID of the project where the compact placement policy is located.ZONE
: the zone where to reserve VMs. You can only reserve VMs in a zone within the region of the specified compact placement policy.RESERVATION_NAME
: the name of the reservation.REGION
: the region where the compact placement policy is located.POLICY_NAME
: the name of an existing compact placement policy. You can't specify a compact placement policy with a fixed number of VMs. Otherwise, creating the reservation fails.NUMBER_OF_VMS
: the number of VMs to reserve, which can't be higher than the supported maximum number of VMs for the specified compact placement policy.MACHINE_TYPE
: a supported machine type for compact placement policies.
For more information about the configuration options and creation methods for single-project reservations, see Create a reservation for a single project.
Create an instance template with a compact placement policy
If you want to create a regional instance template, then you must create the template in the same region of the compact placement policy. Otherwise, creating the instance template fails.
After you create an instance template, you can use it to do the following:
To create an instance template that specifies a compact placement policy, select one of the following options:
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 compact placement policy, run the following command:
gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \
--machine-type=MACHINE_TYPE \
--maintenance-policy=MAINTENANCE_POLICY \
--resource-policies=POLICY_NAME
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.MACHINE_TYPE
: a supported machine type for compact placement policies.MAINTENANCE_POLICY
: the host maintenance policy of the VM. If the compact placement policy you specify uses a maximum distance value of1
or2
, you can only specifyTERMINATE
. Otherwise, you can specify eitherMIGRATE
orTERMINATE
.POLICY_NAME
: the name of an existing compact placement policy. If the compact placement policy specifies a fixed number of VMs, then you must include the--no-restart-on-failure
flag. This indicates that the VMs created using the instance template don't automatically restart after an host error.
REST
To create an instance template that specifies a compact 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 compact
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"
],
"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.INSTANCE_TEMPLATE_NAME
: the name of the instance template.IMAGE
orIMAGE_FAMILY
: specify one of the following:IMAGE
: a specific version of the OS image; for example,debian-10-buster-v20200309
.IMAGE_FAMILY
: an image family. This specifies the most recent, non-deprecated OS image. For example, if you specifyfamily/debian-10
, the latest version in the Debian 10 image family is used. For more information about using image families, see Image families best practices.
MACHINE_TYPE
: a supported machine type for compact placement policies.POLICY_NAME
: the name of an existing compact placement policy. If the compact placement policy specifies a fixed number of VMs, then, in thescheduling
field, you must include theautomaticRestart
field set tofalse
. This indicates that the VMs created using the instance template don't automatically restart after an host error.MAINTENANCE_POLICY
: the host maintenance policy of the VM. If the compact placement policy you specify uses a maximum distance value of1
or2
, you can only specifyTERMINATE
. Otherwise, you can specify eitherMIGRATE
orTERMINATE
.
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:
If you want to apply a compact placement policy to a MIG, then 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.
Create a MIG with a compact placement policy
You can only create VMs that specify a compact 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 compact placement policy, select one of the following options:
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.
For example, to create a regional MIG with default VM properties and the
any-single-zone distribution shape, make a POST
request as follows:
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 to create MIGs, see Basic scenarios for creating MIGs.
Apply a compact placement 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 compact placement policy, select one of the following options:
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.
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
methods.
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 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.
To verify the physical location of a VM that specifies a placement policy in relation to other VMs, select one of the following options:
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 maximum distance value of2
. 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 maximum distance value of1
. 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 maximum distance value of2
. 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 maximum distance value of1
. 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: