Set a target distribution shape for VMs in a regional MIG

If you use a regional managed instance group (MIG), you can set that MIG's target distribution shape to 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 an EVEN 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 the comparison table, use cases, and how distribution shapes work.

Set a target distribution shape when creating your regional MIG or update the target shape of an existing regional MIG.

Before you begin

If you haven't already, then 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 by selecting one of the following options:

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
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.
Terraform

To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
1. Install the Google Cloud CLI.
2. To initialize the gcloud CLI, run the following command:
  gcloud init
3. If you're using a local shell, then create local authentication credentials for your user account:
  gcloud auth application-default login
  You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment.
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.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

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 stateful configuration that are not available in all selected zones, the following limitations apply:
- You must set the target distribution shape to BALANCED, ANY, or ANY_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 of the selected zones.
- If you want to update the MIG's configuration (for example, instance template) to a configuration that cannot be instantiated in all selected zones, you must remove managed instances from all unsupported zones before setting the new configuration.
To set the target distribution shape to BALANCED or ANY_SINGLE_ZONE, you must disable proactive instance redistribution.
If you want to autoscale a regional MIG, you must set the group's target distribution shape to BALANCED or EVEN.
If you set the target distribution shape to BALANCED, ANY, or ANY_SINGLE_ZONE, the following limitations apply:
- Canary updates with two versions are not supported.
- In case of limited availability of requested resources in the whole region, the group might schedule VM instance creation in a zone where the resources are already unavailable. You can try decreasing and increasing group size to get the requested resources in other zones.
- Rolling updates that use the SUBSTITUTE replacement method will try to create the new updated instances in the same zone as the outdated machines, even if the zone doesn't have resources to accommodate the requirements of the new version. To mediate this behavior, you can delete the outdated VMs from the constrained zone, then increase the group size by the number of the deleted VMs. The group creates instances from the latest template in zones where capacity is available.
- If you want to update the group's instance template to a template that specifies resources that are not available in all selected zones, you must remove managed instances from unsupported zones before setting the new template.
If you set the target distribution shape to ANY_SINGLE_ZONE and the group has existing VMs in a single zone, you can create additional VMs in that zone only. If you want to use a different zone, you must first scale in the group to zero VMs.
If you need to provision a group of sole-tenant VMs, you must set the MIG's target distribution shape to EVEN. Create your node groups in the same zones as the MIG's zones and set the MIG's node affinities in the MIG's instance template.

Warning: If you set the target distribution shape to BALANCED, ANY, or ANY_SINGLE_ZONE, the MIG might create VMs outside of your sole-tenant nodes.

Creating a group with a target distribution shape

To create your group, select its zones, and set its target distribution shape, use the Google Cloud console , the gcloud CLI, Terraform, or REST.

Permissions required for this task

To perform this task, you must have the following permissions:

All permissions required to call the regionInstanceGroupManagers.insert method.

Console

In the Google Cloud console, go to the Instance groups page.
Go to the Instance groups page
Click Create instance group to create a new instance group.
Select one of the New managed instance group options: stateless (default) or stateful.
Assign a name and optionally a description to your instance group.
Choose an instance template for the instance group or create a new one.
Specify the number of VMs for this group. For highly available workloads, remember to provision enough VMs to support your application if a zone failure happens.
Under Location, select Multiple zones.
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, select all available zones.
- Note that you cannot update a regional MIG to use different zones after it is created.
Choose a target distribution shape.
1. If you want to select Any or Any single zone, in the Autoscaling section, click Autoscaling mode and choose Delete autoscaling configuration.
2. If you want to select Any single zone or Balanced, in the Instance redistribution section, don't select Allow instance redistribution.
Continue with the rest of the MIG creation process.

gcloud

Use the gcloud compute instance-groups managed create command and include the --target-distribution-shape flag.

gcloud compute instance-groups managed create INSTANCE_GROUP_NAME \
    --template TEMPLATE \
    --size SIZE \
    --region REGION \
    --zones ZONES \
    --target-distribution-shape SHAPE

Replace the following:

INSTANCE_GROUP_NAME: the name of the instance group.
TEMPLATE: the name of the instance template to use for 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 region where 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 region with the following command:
```
gcloud compute zones list --filter=region:REGION --format='list(NAME)'
```
- Note that you cannot update a regional MIG to use different zones after it is created.
SHAPE: the target distribution shape. This can be one 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 an EVEN 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 target distribution shape, set the --target-distribution-shape flag to balanced.

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 the machine type, boot disk image, network, and other VM properties that you want for each VM in your MIG, create an instance template.

To create a regional MIG, use the google_compute_region_instance_group_manager resource.

The following example creates a regional MIG with BALANCED target distribution 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, see Basic Terraform commands.

REST

Call the regionInstanceGroupManagers.insert method. In the request body, include the distributionPolicy property, and set its targetShape 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 instance group.
TEMPLATE: the name of the instance template to use for the instance group.
SIZE: the target size of the instance group.
ZONE: the name of a zone in the region where you want 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 region by calling the regions.get method.
- Note that you cannot update a regional MIG to use different zones after it is created.
SHAPE: the target distribution shape. This can be one 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 an EVEN 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 the target distribution shape in an existing regional MIG but with the following limitations:

If you want to change the target distribution shape to BALANCED or ANY_SINGLE_ZONE, you must first disable proactive redistribution.
If you want to change the target distribution shape to EVEN and if the current distribution of instances is uneven, you must first disable proactive redistribution.
If you change the shape to EVEN and you want to re-enable proactive redistribution, you must first manually rebalance the group.
If you want to change the target distribution shape to EVEN but your instance template specifies resources that are not supported in all selected zones, you must first update the group's instance template to one that is supported in all selected zones.

Permissions required for this task

To perform this task, you must have the following permissions:

compute.instanceGroupManagers.update on the instance group

Console

In the Google Cloud console, go to the Instance groups page.
Go to the Instance groups page
Under the Name column of the list, click the name of the instance group where you want to change the target distribution shape.
Click Edit to modify this managed instance group.
Under Target distribution shape, specify the shape you want.
Click Save to apply the new template.

gcloud

Use the gcloud compute instance-groups managed update command and include the --target-distribution-shape flag.

gcloud compute instance-groups managed update INSTANCE_GROUP_NAME \
    --target-distribution-shape SHAPE

Replace the following:

INSTANCE_GROUP_NAME: the name of the instance group.
SHAPE: the target distribution shape. This can be one 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 an EVEN 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 the regionInstanceGroupManagers.patch method. In the request body, include the distributionPolicy property, and set its targetShape 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 be one 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 an EVEN 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 following permissions:

compute.instanceGroupManagers.get on the instance group

Console

In the Google Cloud console, go to the Instance groups page.
Go to the Instance groups page
If you have existing instance groups, the page lists those groups.
Click the name of the instance group that you want to examine. A page opens with the instance group properties and a list of instances that are included in the group.
Click Details.
In the Location section, look for Target distribution shape.

gcloud

Run the gcloud compute instance-groups managed describe command.

gcloud compute instance-groups managed describe INSTANCE_GROUP_NAME \
    --region REGION

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

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

REST

Construct a GET request to the regionInstanceGroupManagers.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 the distributionPolicy.targetShape field. For example:

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

What's next

Learn more about Viewing info about MIGs and their VMs.
Learn about Working with VMs in a MIG, including adding, recreating, and removing VMs, and updating VM configuration.