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

• If you want to use the API examples in this guide, set up API access.
• If you want to use the command-line examples in this guide, install the gcloud command-line tool.
• Create an instance template.

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.

Note: Set your update type to OPPORTUNISTIC to prevent a race between selectively initiated updates and automatic proactive updates. For more information, see Setting up an opportunistic or proactive update.

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

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]

Use the update-instances command to apply the update to specific instances.

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.

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
}

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 immediately update
• INSTANCE_NAME_1 and INSTANCE_NAME_2: the names of the instances to immediately 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

Minimal action and most disruptive allowed action

Depending on the nature of an update, it might disrupt the instance's state. For example, changing an instance's boot disk requires deleting and replacing the instance.

You can control the level of disruption by using the minimal-action and most-disruptive-allowed-action flags:

• minimal-action lets you apply a more disruptive action than is necessary. 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 apply a restart to pick up metadata changes.
• most-disruptive-allowed-action lets you prevent an update if it requires more disruption than you can afford.

When updating selected instances, both of these flags accept the following actions:

Action	Description	Which instance properties can be updated?
NONE	Do not disrupt the instance at all.	None
REFRESH	Do not stop the instance.	Additional disks, instance metadata, labels
RESTART	Stop the instance and start it again.	Additional disks, instance metadata, labels, machine type
REPLACE	Delete the instance and create it again.	All instance properties stored in the instance template or per-instance configuration

By default, the minimal-action is NONE. If your update requires a more disruptive action than you set with this flag, Compute Engine performs the necessary action to execute the update.

By default, the most-disruptive-allowed-action is REPLACE. If your update requires a more disruptive action than the action you set with this flag, the update request fails. For example, if you set RESTART as the most disruptive allowed action, then an attempt to update the boot disk image fails because that update requires instance recreation, a more disruptive action than a restart.

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

What's next

• Learn about Getting info about MIGs and managed instances.
• Learn about Creating instance templates.
• Learn how to use image families and a rolling replace to update the OS image on all VMs in a MIG.