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

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

• Required: Instance template
• Optional: All-instances configuration
• Optional: Stateful configuration

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

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

• Automatic rollouts with a disruption budget and optional canary updates ofnew templates
• Selective, manual updates to specific VMs only, to minimize disruption
• Re-creation of specific VMs

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

If you only need to resize a MIG, see the documentation for how toadd or remove VMs in a MIG.If you want to learn about configuring MIG features, see the docs forautoscaling,autohealing,load balancing,andstateful workloads.

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity 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. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud 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. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

Configuration components for VMs in a MIG

You configure the VMs in a MIG through the following components:

If you update any configuration for the group through those components, youmust apply the updated configuration to existing VMs in the group in order tomake 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 configurationto existing VMs in the group by using the following methods:

• Automatic (proactive): Use this method if you want the MIG toautomatically apply new configurations to all or to a subset ofexisting VMs in the group. The level of disruption to running VMs depends onthe update policy that you configure. You can use this method to canary updatenew instance templates. To use this method, set the MIG's update type to"proactive".
• Selective (opportunistic): Use this method if you want to apply theupdate manually or if you want to update all existing VMs in the group atonce. You target any or all VMs to be updated to the latest configuration. Touse this method, set the MIG's update type to "opportunistic".
• Re-creation of VMs: Apply new configurations by re-creating specific VMs.

For more information about setting a MIG's update type, seeSet up a proactive or an opportunistic update.

Automatic (proactive)

An automatic update type is also known as aproactive update type. When youset the MIG's update type to proactive, the MIG automatically applies updatedconfigurations to VMs as necessary.

Setting the MIG's update type to proactive offers two primary advantages:

• The rollout of an update happens automatically to your specifications, withoutthe need for additional input after the initial request. You can specify thespeed of deployment, the level of disruption to your service, and the scope ofthe update.
• You can automate partial rollouts, which allows for canary testing.

To learn how to set the MIG's update type, seeSet up a proactive or an opportunistic update.

For more information about automatic rollouts, seeAutomatically apply VM configuration updates in a MIG.

Selective (opportunistic)

A selective update type is also known as anopportunistic update type. Whenyou set the MIG's update type to opportunistic, the MIG applies newconfigurations to existing VMs only when you selectively target specific VMs tobe updated.

Setting the MIG's update type to opportunistic offers the following advantages:

• You can select the VMs that you want to update.
• You can control the timing and the sequence of the updates.
• You can use the gcloud CLI or REST to update allinstances immediately.

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

• One of the VMs in your MIG goes down and needs to be repaired but you don'twant its configuration to change. If you set the MIG's update typeto opportunistic and you do not forcefully applyupdates during repairs, thenCompute Engine repairs the VM using the same configuration that wasused to create that VM, even if the original instance template no longerexists.

• You have an autoscaled MIG and you want to apply a non-critical update withoutany urgency. To ensure that Compute Engine does not tear down yourexisting VMs to apply the update, set the MIG's update type to opportunistic.When scaling in, the autoscaler preferentially terminates VMs with the oldconfiguration. When the group scales out, it creates VMs with the latestconfiguration.

To learn how to set the MIG's update type, seeSet up a proactive or an opportunistic update.

For more information about selectively updating VMs, seeSelectively apply VM configuration updates in a MIG.

Re-creation of VMs

You can re-create any VM in a MIG. When you do, the MIG applies anyupdated configuration that has not yet been applied to that VM. For moreinformation, seeRe-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 updatetype to "proactive". To apply new configurations to existing VMs only when youselect a VM to be updated, set the MIG's update type to "opportunistic".

Use the Google Cloud console, the Google Cloud CLI, or REST.

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

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

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",    }]}

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

• Automatically apply VM configuration updates in a MIG
• Selectively apply VM configuration updates in a MIG

Check your group's update policy type

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

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

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

To change the policy type, seeSet 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 runningVMs.If you configure automatic (proactive) updates, the MIG updates the VMs inthe following order:

1. Running, suspended, and stopped VMs
2. VMs with statusSUSPENDING orSTOPPING

For an automatic update, the MIG calculates themaximum surgeandmaximum unavailablebased on the target number of running VMs only, and doesn't consider the VMs inthe standby pool.

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

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

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

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

Canary updates

If you want to initiatecanary updatesin a MIG that has suspended or stopped VMs, the following applies:

• In themanual standby policy mode, the MIG updates only the running VMsbased on the number or percentage of VMs to which you want to apply theupdate. The suspended and stopped VMs remain in the previous versions.
• In thescale-out-pool standby policy mode, you cannot initiate a canaryupdate in the MIG.

Relationship betweenversions andinstanceTemplate fields

If you use REST, we recommend using theinstanceGroupManagers.versions andregionInstanceGroupManagers.versionsfields to configure instance templates for zonal and regional MIGs.

The legacyinstanceTemplate field overlaps in functionality with theversions field because both fields let you specify which instance template theMIG uses to create VMs. However, only theversions field lets youspecify an advanced two-template (canary) configuration.

For backward compatibility, MIGs continue to supportsetting the top-levelinstanceTemplate field, even though we recommendthat you switch to using only theversions field. Using both the top-levelinstanceTemplate field and theversionsfield at the same time can lead to ambiguity and confusion.

If you specify both theinstanceTemplate field and theversions field whencalling theupdate() orpatch() 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 newinstance template is applied to the MIG.

  For example, in the following request, the top-levelinstanceTemplate andtheversions field specify the same instance template which is differentfrom the existing current template, so the MIG is updatedto 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 valuediffers from the current instance template in the MIG.

  This is a valid request. The field that's different from the current settingis taken as the intended value. For example, you call theupdate() methodand 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 valuesdiffer from the current instance template in the MIG.

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

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

Theversions field,instanceTemplate field, and theget() method

If you only specify one instance template, either through the top-levelinstanceTemplate field or through theversions field or through both, theget() method returns both fields in its response. This makes the newversions field backward compatible. As long as you specify a single instancetemplate in either of these fields, there is no change to what theget()method returns in theinstanceTemplate field.

If theversions field has two instance templates specified, theget() methodreturns an empty top-levelinstanceTemplate field. There is no way tounambiguously express a canary, two-instance template configuration inthe top-levelinstanceTemplate field, so the field is not used during a canaryupdate.

Theversions field and thesetInstanceTemplate() method

For backward compatibility, thesetInstanceTemplate() method behaves as ithas previously, letting you change the template the MIGuses to create VMs. When you call this method, theversions field is overridden with the instance template specified by thesetInstanceTemplate() method.

ThesetInstanceTemplate() method also sets theupdatePolicy toOPPORTUNISTIC. Thisprevents the MIG from actively deploying an instance templatethat isn't explicitly specified in theversions field.

What's next

• Learn more aboutautomatically rolling out a new instance template to a MIG.
• Learn more aboutselectively updating VMs in a MIG.
• View informationabout your MIG and its VMs.