Selectively updating instances in a MIG

This document describes how to selectively apply a new instance template to specific virtual machine (VM) instances in a managed instance group (MIG). If you want to automate the rollout of a new instance template to all or to a random subset of the virtual machine (VM) instances in a MIG, see Automatically rolling out updates to instances in a MIG instead. To help you decide, see Choosing between automated and selective updates.

If you have a stateful MIG, you can also use the methods on this page to apply new or updated per-instance configurations.

Selectively initiating updates lets you:

  • Select specific instances that you would like to update.
  • 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. When selectively initiating the update, the minimal necessary action is automatically performed.
  • 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.
  • Prevent an update if it requires more disruption than you can afford.
  • Perform an update of all selected instances immediately, without restricting the rollout by any Updater options, such as maxSurge and maxUnavailable constraints.

Before you begin

Updating selected instances

When you specify a new template and want to apply it only to selected instances, the MIG still automatically applies the new template to new instances that are created when the MIG is resized. For existing instances, you can apply the new template to selected instances using the gcloud tool or the Compute Engine API.

gcloud

To set up a new instance template for your group, use the set-instance-template command.

gcloud compute instance-groups managed set-instance-template INSTANCE_GROUP_NAME \
    --template=INSTANCE_TEMPLATE \
    [--zone=ZONE | --region=REGION]

To apply the update to specific instances, use the update-instances command.

gcloud compute instance-groups managed update-instances INSTANCE_GROUP_NAME \
    --instances INSTANCE_NAMES \
    --most-disruptive-allowed-action DISRUPTION_LEVEL \
    --minimal-action DISRUPTION_LEVEL

Replace the following:

  • INSTANCE_GROUP_NAME: the name of the MIG
  • INSTANCE_TEMPLATE: new instance template
  • INSTANCE_NAMES: a list of instances to apply the template to
  • DISRUPTION_LEVEL: the minimal or maximal disruption level: none, refresh, restart, or replace
    • The default minimal action is none
    • The default most disruptive allowed action is replace

API

Call the patch method on a regional or zonal MIG and update the versions.instanceTemplate field. To avoid automatically rolling out the new template to all instances in the group, set the updatePolicy.type field to OPPORTUNISTIC.

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

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

After setting up a new template version, call applyUpdatesToInstances for the regional or zonal MIG. Specify a list of instances in the request or, alternatively, set the allInstances boolean to true to update all instances.

Update specific instances

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/applyUpdatesToInstances
{
  "instances": [
    "zones/ZONE/instances/INSTANCE_NAME_1",
    "zones/ZONE/instances/INSTANCE_NAME_2"
  ],
  "minimalAction": DISRUPTION_LEVEL,
  "mostDisruptiveAllowedAction": DISRUPTION_LEVEL
}

Update all instances

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/applyUpdatesToInstances
{
  "allInstances": true,
  "minimalAction": DISRUPTION_LEVEL,
  "mostDisruptiveAllowedAction": DISRUPTION_LEVEL
}

Replace the following:

  • INSTANCE_GROUP_NAME: the name of the group
  • NEW_TEMPLATE: the name of the new template
  • ZONE: the zone of an instance to update
  • INSTANCE_NAME_1 and INSTANCE_NAME_2: the names of the instances to update
  • DISRUPTION_LEVEL: the minimal or maximal disruption level: NONE, REFRESH, RESTART, or REPLACE
    • The default minimalAction is NONE.
    • The default mostDisruptiveAllowedAction is REPLACE.

Similar to other managed instance group methods, applyUpdatesToInstances is intent-based, which means it returns an operation response. The operation can take some time to complete.

After you make a request, you can check the status to verify that the update is complete.

Updating per-instance configs

When you apply an update to a selected instance, the MIG applies both the instance template and the per-instance configuration, if it exists.

For more information, see Applying stateful configuration from per-instance configurations

Controlling the disruption level during selective updates

Depending on the nature of an update, it might disrupt an instance's state. For example, changing an instance's boot disk requires replacing the instance. You can control the level of disruption during a selective update by setting the following options:

  • Minimal action: Use this option to minimize disruption as much as possible or to apply a more disruptive action than is necessary.

    • To limit disruption as much as possible, set the minimal action to NONE. If your update requires a more disruptive action, Compute Engine performs the necessary action to execute the update.
    • To apply a more disruptive action than is strictly necessary, set the minimal action to RESTART or REPLACE. For example, Compute Engine does not need to restart a VM to change its metadata. But if your application reads instance metadata only when a VM is restarted, you can set the minimal action to RESTART in order to pick up metadata changes.
  • Most disruptive allowed action: Use this option to prevent an update if it requires more disruption than you can afford. If your update requires a more disruptive action than you set with this flag, the update request fails. For example, if you set the most disruptive allowed action to RESTART, then an attempt to update the boot disk image fails because that update requires instance recreation, a more disruptive action than a restart.

When updating selected instances, both of these options accept the following values:

ValueDescriptionWhich instance properties can be updated?
NONEDo not disrupt the instance at all.None
REFRESHDo not stop the instance.Additional disks, instance metadata, labels, tags
RESTARTStop the instance and start it again.Additional disks, instance metadata, labels, tags, machine type
REPLACEDelete the instance and create it again.All instance properties stored in the instance template or per-instance configuration

The most disruptive allowed action can't be less disruptive than the minimal action.

When you selectively update instances, the following defaults apply:

  • The default minimal action is NONE, which limits disruption as much as possible.
  • The default most disruptive allowed action is REPLACE. If you cannot tolerate such disruption, set the most disruptive allowed action to be less disruptive.

What's next