Updating instances in a MIG

This document helps you decide how to apply instance template and per-instance configuration updates to the virtual machine (VM) instances in a managed instance group (MIG).

You might want to update a MIG's instance template for the following reasons:

To update your application or the operating system on each instance.
To perform an A/B test to compare different versions of the same application.
To perform a canary update to minimize disruption when testing a new version.
To change other specifications for the instances in your MIG, such as the machine type or disk options.

Apply a new version of an instance template by using one of the following methods:

Automated rolling update. The MIG automatically rolls out a new version of an instance template to all or to a random subset of managed instances in the MIG. The scope of the update and the level of disruption depends on the update policy that you configure.
Selective update of specific instances. You can specifically target selected instances for an update. Use this method for stateful MIGs or if you want to orchestrate the update manually.

If you have a stateful MIG, you can also use a selective update to apply changes that you make to per-instance configurations.

If you only need resize a MIG, see the documentation for how to add or remove instances in a MIG.

Limitations

You cannot use an automated rolling update if your MIG has any stateful configuration. Instead, control updates and limit disruption with a selective update of specific instances.
If you use custom instance names and don't configure stateful disks or metadata, you can use automated updates. But, to preserve instance names, you must set the replacement method to RECREATE.

Choosing between automated and selective updates

To automatically roll out a new template to all or to a subset of the instances in a stateless MIG, set the MIG's update type to PROACTIVE. If you have a stateful MIG or if an automated update is potentially too disruptive, set the MIG's update type to OPPORTUNISTIC then selectively update specific instances.

Automated, proactive updates

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

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

When you start a proactive rolling update, the MIG actively schedules actions to apply the requested updates to instances as necessary. In many cases, this means deleting and recreating instances proactively.

For more information, see Automatically rolling out updates to instances in a MIG.

Selective updates

Selectively updating specific instances offers the following advantages:

You can select the instances that you want to update.
You can apply an update with the least amount of disruption that is necessary for the update to complete. For example, if you are only updating metadata, it might not be necessary to restart the instance to complete the update. By default, the minimal necessary action is automatically performed.
You can enforce instance restart or recreation even if those actions aren't necessary for applying the update. For example, you might want to restart a VM even if you're only updating its metadata because your guest software has to pick up the new metadata on VM boot.
You can prevent an update if it requires more disruption than you can afford.

To prevent a proactive update from competing with your selective updates, set the MIG's update type to OPPORTUNISTIC.

Opportunistic updates

When the update type is set to OPPORTUNISTIC, the MIG applies updates only when you selectively apply the update to specific instances or when new instances are created by the MIG. A MIG creates new instances when it is resized to add instances, either automatically or manually. Compute Engine does not actively initiate requests to apply opportunistic updates.

In certain scenarios, an opportunistic update is useful because you don't want to cause instability to the system if it can be avoided. For example, if you have a non-critical update that can be applied as necessary without any urgency and you have a MIG that is actively being autoscaled, perform an opportunistic update so that Compute Engine does not actively tear down your existing instances to apply the update. When resizing down, the autoscaler preferentially terminates instances with the old template as well as instances that are not yet in a RUNNING state.

For more information, see Selectively updating instances in a MIG.

Setting up an opportunistic or proactive update

By default, updates initiated by using the Cloud Console or the gcloud command-line tool are proactive, which means that they start automatically, and updates initiated by using the Compute Engine API are opportunistic, which means that the MIG does not proactively apply the new template to existing instances.

To choose whether an update is opportunistic or proactive, set the mode to opportunistic or proactive by using the Cloud Console, the gcloud command-line tool, or the Compute Engine API.

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 Cloud Console, go to the Instance groups page.

Go to the Instance groups page
Select the MIG you want to update.
At the top of the page, click Rolling update.
Under Update mode, choose between either an opportunistic or proactive update.

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=INSTANCE_TEMPLATE \
    --type=opportunistic|proactive \
    [--zone=ZONE | --region=REGION]

API

Call the patch method on a regional or zonal 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:

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 instances in a MIG, see the following pages:

Relationship between `versions` and `instanceTemplate` fields

If you use the Compute Engine API, 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 instances. 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 instances. 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 instances in a MIG.
Learn about using image families to perform one-click OS upgrades in a MIG.