Set a target distribution shape for VMs in a regional MIG

If you use aregional managed instance group (MIG),you can set that MIG'starget distribution shapeto one of the following options:

  • EVEN (default): the group creates and deletes VMs to achieve and maintain the same number of VMs across the selected zones. In anEVEN distribution, the number of VMs does not differ by more than 1 between any two zones. Recommended for highly available serving workloads.
  • BALANCED: the group prioritizes creation of VMs in zones where resources are available, while distributing VMs as evenly as possible across selected zones to minimize the impact of zonal failure. Recommended for highly available serving or batch workloads.
  • ANY: the group picks zones for creating VM instances to fulfill the requested number of VMs within present resource constraints and to maximize utilization of unused zonal reservations. Recommended for batch workloads that do not require high availability.
  • ANY SINGLE ZONE: the group creates all VM instances within a single zone. The zone is chosen based on hardware support, current resource and quota availability, and matching reservations. Recommended in combination with a compact instance placement policy for workloads that require extensive communication between VMs.

To use reserved VMs in a regional managed instance group, create identical reservations with the same name in each applicable zone. Then, target those reservations by name in the group's instance template.

To help you choose a shape, see thecomparison table,use cases,andhow distribution shapes work.

Set a target distribution shape whencreating your regional MIGorupdatethe target shape of an existing regional MIG.

Before you begin

Limitations

  • You can only select zones for your MIG when you create the MIG.

  • If you specify resources in your MIG's instance template or statefulconfiguration that are not available in all selected zones, the followinglimitations apply:

    • You must set thetarget distribution shapetoBALANCED,ANY, orANY_SINGLE_ZONE.
    • You must ensure that any resources required by the MIG–for example,existing disks, machine types, or GPUs–are available in at least one ofthe selected zones.
    • If you want to update theMIG's configuration (for example, instancetemplate) to a configuration that cannot be instantiated in all selectedzones, you mustremove managed instancesfrom all unsupported zones before setting the new configuration.

  • To set the target distribution shape toBALANCED orANY_SINGLE_ZONE,you must disableproactive instance redistribution.

  • If you set the target distribution shape toBALANCED,ANY, orANY_SINGLE_ZONE, the following limitations apply:

    • Canaryupdates with twoversionsare not supported.
    • In case of limited availability of requested resources in the wholeregion, the group might schedule VM instance creation in a zone where theresources are already unavailable. You can try decreasing and increasinggroup size to get the requested resources in other zones.
    • Rolling updates that use theSUBSTITUTEreplacement methodwill try to create the new updated instances in the same zone as theoutdated machines, even if the zone doesn't have resources to accommodatethe requirements of the new version. To mediate this behavior, you candelete the outdated VMs from the constrained zone, then increase the groupsize by the number of the deleted VMs. The group creates instances fromthe latest template in zones where capacity is available.
    • If you want to update the group's instance template to a template thatspecifies resources that are not available in all selected zones, you mustremovemanaged instances from unsupported zones before setting the new template.

  • If you set the target distribution shape toANY_SINGLE_ZONE and the grouphas existing VMs in a single zone, you can create additional VMs in that zoneonly. If you want to use a different zone, you must first scale in the groupto zero VMs.

  • If you need toprovision a group of sole-tenant VMs,you must set the MIG's target distribution shape toEVEN. Create your nodegroups in the same zones as the MIG's zones and set the MIG's node affinitiesin the MIG's instance template.

    Warning: If you set the target distribution shape toBALANCED,ANY, orANY_SINGLE_ZONE, the MIG might create VMs outside of your sole-tenantnodes.

Creating a group with a target distribution shape

To create your group, select its zones, and set its target distribution shape,use theGoogle Cloud console, thegcloud CLI,Terraform, orREST.

Permissions required for this task

To perform this task, you must have the followingpermissions:

Console

  1. In the Google Cloud console, go to theInstance groups page.

    Go to the Instance groups page

  2. ClickCreate instance group to create a new instance group.
  3. Select one of theNew managed instance group options: stateless(default) orstateful.
  4. Assign a name and optionally a description to your instance group.
  5. Choose an instance template for the instance group or create a new one.
  6. Specify the number of VMs for this group. For highly available workloads,remember toprovisionenough VMs to support your application if a zone failure happens.
  7. UnderLocation, selectMultiple zones.

  8. Choose a region and select the zones you want to use.

    • If you want your MIG to be able to use all zones in the region, selectall available zones.
    • Note that you cannot update a regional MIG to use different zones afterit is created.

  9. Choose a target distribution shape.

    If you selectAny single zone orBalanced, then in theInstanceredistribution section, don't selectAllow instance redistribution.

  10. Continue with the rest of the MIG creation process.

gcloud

Use thegcloud compute instance-groups managed create commandand include the--target-distribution-shape flag.

gcloud compute instance-groups managed createINSTANCE_GROUP_NAME \    --templateTEMPLATE \    --sizeSIZE \    --regionREGION \    --zonesZONES \    --target-distribution-shapeSHAPE

Replace the following:

  • INSTANCE_GROUP_NAME: the name of the instancegroup.
  • TEMPLATE: the name of the instance template to usefor the group.
  • SIZE: the target size of the instance group.
  • REGION: the region where you want your group.

  • ZONES (optional): a list of zones in the regionwhere you want to deploy VM instances. By default, Compute Engine selects three zones for you.

    • If you want your MIG to be able to use all zones in the region,specify all the available zones. You can get a list of zones in regionwith the following command:

      gcloud compute zones list --filter=region:REGION --format='list(NAME)'

    • Note that you cannot update a regional MIG to use different zonesafter it is created.

  • SHAPE: the target distribution shape. This can beone of the following values:

    • even (default): the group creates and deletes VMs to achieve and maintain the same number of VMs across the selected zones. In anEVEN distribution, the number of VMs does not differ by more than 1 between any two zones. Recommended for highly available serving workloads.
    • balanced: the group prioritizes creation of VMs in zones where resources are available, while distributing VMs as evenly as possible across selected zones to minimize the impact of zonal failure. Recommended for highly available serving or batch workloads.
    • any: the group picks zones for creating VM instances to fulfill the requested number of VMs within present resource constraints and to maximize utilization of unused zonal reservations. Recommended for batch workloads that do not require high availability.
    • any-single-zone: the group creates all VM instances within a single zone. The zone is chosen based on hardware support, current resource and quota availability, and matching reservations. Recommended in combination with a compact instance placement policy for workloads that require extensive communication between VMs.

For example, to create a regional MIG with a balanced targetdistribution shape, set the--target-distribution-shape flag tobalanced.

gcloud compute instance-groups managed create example-rmig \    --template example-template \    --size 30 \    --zones us-east1-b,us-east1-c \    --target-distribution-shape balanced \    --instance-redistribution-type none

Terraform

If you haven't already created an instance template, which specifies themachine type, boot disk image, network, and other VM properties that youwant for each VM in your MIG,create an instance template.

To create a regional MIG, use thegoogle_compute_region_instance_group_managerresource.

The following example creates a regional MIG withBALANCED targetdistribution shape.

resource "google_compute_region_instance_group_manager" "default" {  name                             = "example-rmig"  region                           = "us-east1"  distribution_policy_zones        = ["us-east1-b", "us-east1-c"]  distribution_policy_target_shape = "BALANCED"  update_policy {    type                         = "PROACTIVE"    minimal_action               = "REFRESH"    instance_redistribution_type = "NONE"    max_unavailable_fixed        = 3  }  target_size        = 30  base_instance_name = "instance"  version {    instance_template = google_compute_instance_template.default.id  }}

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

REST

Call theregionInstanceGroupManagers.insert method.In the request body, include thedistributionPolicy property, and set itstargetShape field.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers{    "name":INSTANCE_GROUP_NAME,    "instanceTemplate": "global/instanceTemplates/TEMPLATE",    "targetSize":SIZE,    "distributionPolicy": {        "zones": [            {"zone": "zones/ZONE1"},            {"zone": "zones/ZONE2"},            {"zone": "zones/ZONE3"},        ],        "targetShape": "SHAPE"    }}

Replace the following:

  • PROJECT_ID: the project ID for this request.
  • REGION: the region for the instance group.
  • INSTANCE_GROUP_NAME: the name of the instancegroup.
  • TEMPLATE: the name of the instance template touse for the instance group.
  • SIZE: the target size of the instance group.
  • ZONE: the name of a zone in the region where youwant to deploy VM instances.
    • If you want your MIG to be able to use all zones in the region,specify all the available zones. You can get a list of zones in regionby calling theregions.get method.
    • Note that you cannot update a regional MIG to use different zonesafter it is created.
  • SHAPE: the target distribution shape. This can beone of the following values:
    • EVEN (default): the group creates and deletes VMs to achieve and maintain the same number of VMs across the selected zones. In anEVEN distribution, the number of VMs does not differ by more than 1 between any two zones. Recommended for highly available serving workloads.
    • BALANCED: the group prioritizes creation of VMs in zones where resources are available, while distributing VMs as evenly as possible across selected zones to minimize the impact of zonal failure. Recommended for highly available serving or batch workloads.
    • ANY: the group picks zones for creating VM instances to fulfill the requested number of VMs within present resource constraints and to maximize utilization of unused zonal reservations. Recommended for batch workloads that do not require high availability.
    • ANY_SINGLE_ZONE: the group creates all VM instances within a single zone. The zone is chosen based on hardware support, current resource and quota availability, and matching reservations. Recommended in combination with a compact instance placement policy for workloads that require extensive communication between VMs.

Changing the target distribution shape of an existing group

You can change thetarget distribution shapein an existing regional MIG but with the following limitations:

  • If you want to change the target distribution shape toBALANCED orANY_SINGLE_ZONE, you must firstdisable proactive redistribution.
  • If you want to change the target distribution shape toEVEN and if thecurrent distribution of instances is uneven, you must first disable proactiveredistribution.
  • If you change the shape toEVEN and you want to re-enable proactiveredistribution, you must firstmanually rebalance the group.
  • If you want to change the target distribution shape toEVEN but yourinstance template specifies resources that are not supported in all selectedzones, you must first update the group's instance template to one that issupported in all selected zones.

Permissions required for this task

To perform this task, you must have the followingpermissions:

  • compute.instanceGroupManagers.update on the instance group

Console

  1. In the Google Cloud console, go to theInstance groups page.

    Go to the Instance groups page

  2. In theName column of the list, click the name of the instancegroup where you want to change the target distribution shape.
  3. ClickEdit to modify this managed instance group.
  4. ClickLocation to expand the section.
  5. In theTarget distribution shape list, select the shape that youwant.
  6. ClickSave to apply the changes.

gcloud

Use thegcloud compute instance-groups managed update commandand include the--target-distribution-shape flag.

gcloud compute instance-groups managed updateINSTANCE_GROUP_NAME \    --target-distribution-shapeSHAPE

Replace the following:

  • INSTANCE_GROUP_NAME: the name of the instancegroup.
  • SHAPE: the target distribution shape. This can beone of the following values:
    • even (default): the group creates and deletes VMs to achieve and maintain the same number of VMs across the selected zones. In anEVEN distribution, the number of VMs does not differ by more than 1 between any two zones. Recommended for highly available serving workloads.
    • balanced: the group prioritizes creation of VMs in zones where resources are available, while distributing VMs as evenly as possible across selected zones to minimize the impact of zonal failure. Recommended for highly available serving or batch workloads.
    • any: the group picks zones for creating VM instances to fulfill the requested number of VMs within present resource constraints and to maximize utilization of unused zonal reservations. Recommended for batch workloads that do not require high availability.
    • any-single-zone: the group creates all VM instances within a single zone. The zone is chosen based on hardware support, current resource and quota availability, and matching reservations. Recommended in combination with a compact instance placement policy for workloads that require extensive communication between VMs.

REST

Call theregionInstanceGroupManagers.patch method.In the request body, include thedistributionPolicy property, and set itstargetShape field.

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME{    "distributionPolicy": {        "targetShape": "SHAPE"    }}

Replace the following:

  • PROJECT_ID: the project ID for this request.
  • REGION: the region for the instance group.
  • INSTANCE_GROUP_NAME: the name of the instance group.
  • SHAPE: the target distribution shape. This can beone of the following values:
    • EVEN (default): the group creates and deletes VMs to achieve and maintain the same number of VMs across the selected zones. In anEVEN distribution, the number of VMs does not differ by more than 1 between any two zones. Recommended for highly available serving workloads.
    • BALANCED: the group prioritizes creation of VMs in zones where resources are available, while distributing VMs as evenly as possible across selected zones to minimize the impact of zonal failure. Recommended for highly available serving or batch workloads.
    • ANY: the group picks zones for creating VM instances to fulfill the requested number of VMs within present resource constraints and to maximize utilization of unused zonal reservations. Recommended for batch workloads that do not require high availability.
    • ANY_SINGLE_ZONE: the group creates all VM instances within a single zone. The zone is chosen based on hardware support, current resource and quota availability, and matching reservations. Recommended in combination with a compact instance placement policy for workloads that require extensive communication between VMs.

Viewing the configured instance distribution policy

Permissions required for this task

To perform this task, you must have the followingpermissions:

  • compute.instanceGroupManagers.get on the instance group

Console

  1. In the Google Cloud console, go to theInstance groups page.

    Go to the Instance groups page

    If you have existing instance groups, the page lists those groups.
  2. Click the name of the instance group that you want to examine. A pageopens with the instance group properties and a list of instances thatare included in the group.
  3. ClickDetails.
  4. In theLocation section, look forTarget distribution shape.

gcloud

Run thegcloud compute instance-groups managed describe command.

gcloud compute instance-groups managed describeINSTANCE_GROUP_NAME \    --regionREGION

The command returns the group's details, including thedistributionPolicy.targetShape field:

...distributionPolicy:  targetShape: BALANCED  zones:  - zone: https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f  ...name: my-groupregion: https://www.googleapis.com/compute/v1/projects/my-project/regions/us-central1...

REST

Construct aGET request to theregionInstanceGroupManagers.get method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME

Replace the following:

  • PROJECT_ID: the project ID for this request
  • REGION: the region for the instance group
  • INSTANCE_GROUP_NAME: the name of the instance group

The target distribution shape is returned in thedistributionPolicy.targetShape field. For example:

{  "name": "my-instance-group",  "distributionPolicy": {    "targetShape": "BALANCED",  },  "targetSize": 50,  ...}

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.