Apply new VM configurations in a MIG

This page explains how you can configure the virtual machine (VM) instances in a managed instance group (MIG) and the methods you can use to apply the configuration to existing VMs in the group.

You specify the intended configuration for the VMs in a MIG by using the following VM configuration components:

Whenever you update the intended configuration by using those components, Compute Engine automatically applies your updated configuration to new VMs that are added to the group.

To apply an updated configuration to existing VMs, use the methods described on this page:

You can also configure your MIG to apply the latest available configuration to VMs during VM repairs. For more information, see Apply configuration updates during repairs.

Before you begin

Configuration components for VMs in a MIG

If you update any configuration for the group through those components, you must apply the updated configuration to existing VMs in the group in order to make the updated configuration effective.

Methods to apply a new configuration to existing VMs

After you update a MIG's VM configuration, you can apply the new configuration to existing VMs in the group by using the following methods:

Automatic (proactive)

Component	Properties	Use case
Instance template	Machine type, boot disk image, labels, startup script, network interfaces, and other VM properties	Required: Use an instance template to define required and optional instance properties for all VMs in the group. Optional: If you want to canary test a second VM configuration, you can add a second instance template to the group and apply it to a subset of the VMs in the group.
All-instances configuration	Labels and metadata	Optional: Use an all-instances configuration to quickly override instance template properties for all VMs in the group.
Stateful configuration	Stateful disks, IP addresses, and metadata	Optional: If you need to support a stateful workload, add stateful configuration to VMs in the group.

An automatic update type is also known as a proactive update type. When you set the MIG's update type to proactive, the MIG automatically applies updated configurations to VMs as necessary.

Selective (opportunistic)

A selective update type is also known as an opportunistic update type. When you set the MIG's update type to opportunistic, the MIG applies new configurations to existing VMs only when you selectively target specific VMs to be updated.

In certain scenarios, a selective update type is useful because you don't want to cause instability to the system if it can be avoided. For example, consider the following:

Re-creation of VMs

You can re-create any VM in a MIG. When you do, the MIG applies any updated configuration that has not yet been applied to that VM. For more information, see Re-creating VMs in a MIG.

Set up a proactive or an opportunistic update

To apply new configurations to existing VMs automatically, set the MIG's update type to "proactive". To apply new configurations to existing VMs only when you select a VM to be updated, set the MIG's update type to "opportunistic".

Permissions required for this task

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

For zonal MIGs, all permissions required to call the instanceGroupManagers.patch method
For regional MIGs, all permissions required to call the regionInstanceGroupManagers.patch method

Console

In the Google Cloud console, go to the Instance groups page.

Go to the Instance groups page
Select the MIG that you want to update.
Click Edit.
Click Update policy to expand the section.
Choose either Selective or Automatic update.
Optional: If you choose Automatic, then you can set the additional options or use the default values.
Click Save.

gcloud

Use the rolling-action start-update command and set the --type flag to opportunistic or proactive.

gcloud compute instance-groups managed rolling-action start-update INSTANCE_GROUP_NAME \
    --version=template=NEW_TEMPLATE \
    --type=TYPE

You can also use the beta update command and include the --update-policy-type flag.

gcloud beta compute instance-groups managed update INSTANCE_GROUP_NAME \
    --update-policy-type=TYPE

Replace the following:

INSTANCE_GROUP_NAME: the name of the group
NEW_TEMPLATE: the name of the new template for the group
TYPE: the type of update, opportunistic or proactive

REST

Call the patch method on a zonal or regional MIG resource.

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

{
  "updatePolicy": {
    "type": "TYPE" # Choose an opportunistic or proactive update
  },
  "versions": [{
    "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE",
    }]
}

Replace the following:

PROJECT_ID: the project in which the MIG exists.
REGION: the region where your MIG is located. For a zonal MIG, replace regions/REGION with zones/ZONE.
INSTANCE_GROUP_NAME: the name of the group.
NEW_TEMPLATE: the name of the new template for the group.
TYPE: the type of update, OPPORTUNISTIC or PROACTIVE.

To learn more about setting a new template and then applying that template to new and existing VMs in a MIG, see the following pages:

Check your group's update policy type

You can view your MIG's currently configured update policy type ("opportunistic" or "proactive") and other update policy settings by using the gcloud CLI or REST.

gcloud

Use the describe command and include the --format flag to only list the updatePolicy settings.

gcloud beta compute instance-groups managed describe INSTANCE_GROUP_NAME \
    --format="(updatePolicy)"

REST

Make a GET request on a zonal or regional MIG and check the updatePolicy field.

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

To change the policy type, see Set up a proactive or an opportunistic update.

Updates for suspended and stopped VMs

If you have suspended and stopped pools of VMs in a MIG, you can selectively (opportunistic) update suspended or stopped VMs like you update other running VMs. If you configure automatic (proactive) updates, the MIG updates the VMs in the following order:

Running, suspended, and stopped VMs
VMs with status SUSPENDING or STOPPING

For an automatic update, the MIG calculates the maximum surge and maximum unavailable based on the target number of running VMs only, and doesn't consider the VMs in the standby pool.

If the automatic update requires replacing of VMs in the group, then the MIG does the following:

Deletes the suspended and stopped VMs.
Creates new VMs with the new instance template.
Performs the initialization process.
Suspends or stops the VMs.

If the automatic update requires only refreshing or restarting of VMs in the group, then the MIG does the following:

Resumes or starts the VMs.
Performs the update on the VMs when they are running.
Performs the initialization process.
Suspends or stops the VMs.

Canary updates

If you want to initiate canary updates in a MIG that has suspended or stopped VMs, the following applies:

In the manual standby policy mode, the MIG updates only the running VMs based on the number or percentage of VMs to which you want to apply the update. The suspended and stopped VMs remain in the previous versions.
In the scale-out-pool standby policy mode, you cannot initiate a canary update in the MIG.

Relationship between `versions` and `instanceTemplate` fields

If you use REST, we recommend using the instanceGroupManagers.versions and regionInstanceGroupManagers.versions fields to configure instance templates for zonal and regional MIGs.

The legacy instanceTemplate field overlaps in functionality with the versions field because both fields let you specify which instance template the MIG uses to create VMs. However, only the versions field lets you specify an advanced two-template (canary) configuration.

For backward compatibility, MIGs continue to support setting the top-level instanceTemplate field, even though we recommend that you switch to using only the versions field. Using both the top-level instanceTemplate field and the versions field at the same time can lead to ambiguity and confusion.

If you specify both the instanceTemplate field and the versions field when calling the update() or patch() method, there are three possible outcomes:

You set both fields to the same value.

This is a valid request. In this case, it creates no ambiguity, and the new instance template is applied to the MIG.

For example, in the following request, the top-level instanceTemplate and the versions field specify the same instance template which is different from the existing current template, so the MIG is updated to the new instance template:
```
{
 "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE",
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE"
  }
 ],
 "updatePolicy": {
   "type": "PROACTIVE"
 }
}
```
You set both fields to values that don't match but only one value differs from the current instance template in the MIG.

This is a valid request. The field that's different from the current setting is taken as the intended value. For example, you call the update() method and supply both fields, but only one field is updated:
```
{
 "instanceTemplate": "global/instanceTemplates/CURRENT_TEMPLATE",
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE"
  }
 ],
 "updatePolicy": {
   "type": "PROACTIVE"
 }
}
```

You set both fields to values that don't match, and both values differ from the current instance template in the MIG.

This setting is invalid and returns an error because there is no clear intent.

{
 "instanceTemplate": "global/instanceTemplates/NEW_TEMPLATE",
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/A_DIFFERENT_NEW_TEMPLATE"
  }
 ],
 "updatePolicy": {
   "type": "PROACTIVE"
 }
}

The `versions` field, `instanceTemplate` field, and the `get()` method

If you only specify one instance template, either through the top-level instanceTemplate field or through the versions field or through both, the get() method returns both fields in its response. This makes the new versions field backward compatible. As long as you specify a single instance template in either of these fields, there is no change to what the get() method returns in the instanceTemplate field.

If the versions field has two instance templates specified, the get() method returns an empty top-level instanceTemplate field. There is no way to unambiguously express a canary, two-instance template configuration in the top-level instanceTemplate field, so the field is not used during a canary update.

The `versions` field and the `setInstanceTemplate()` method

For backward compatibility, the setInstanceTemplate() method behaves as it has previously, letting you change the template the MIG uses to create VMs. When you call this method, the versions field is overridden with the instance template specified by the setInstanceTemplate() method.

The setInstanceTemplate() method also sets the updatePolicy to OPPORTUNISTIC. This prevents the MIG from actively deploying an instance template that isn't explicitly specified in the versions field.

What's next

Learn more about automatically rolling out a new instance template to a MIG.
Learn more about selectively updating VMs in a MIG.
View information about your MIG and its VMs.

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

Last updated 2026-06-09 UTC.

Apply new VM configurations in a MIG Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

REST

Configuration components for VMs in a MIG

Methods to apply a new configuration to existing VMs

Automatic (proactive)

Selective (opportunistic)

Re-creation of VMs

Set up a proactive or an opportunistic update

Permissions required for this task

Console

gcloud

REST

Check your group's update policy type

gcloud

REST

Updates for suspended and stopped VMs

Relationship between versions and instanceTemplate fields

The versions field, instanceTemplate field, and the get() method

The versions field and the setInstanceTemplate() method

What's next

Relationship between `versions` and `instanceTemplate` fields

The `versions` field, `instanceTemplate` field, and the `get()` method

The `versions` field and the `setInstanceTemplate()` method