This document describes how to selectively apply configuration updates to thevirtual machine (VM) instances in amanaged instance group (MIG).

Compute Engine maintains the VMs in a MIG based on theconfiguration componentsthat you use: instance template, optional all-instances configuration, andoptional stateful configuration.

Whenever you update a MIG's VM configuration by changing 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, you can set up a selectiveupdate–also known as a "opportunistic" update type. This type of update offersthe 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 allVMs immediately.

Alternatively, if you want to automate the rollout of a new configuration toall or to a random subset of the VMs in a MIG, seeAutomatically apply VM configuration updates in a MIG.To help you decide, seeMethods to apply a new configuration to existing VMs.

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.

Apply updated configuration to selected VMs

Ensure your group's update policy type is set to "opportunistic" to preventthe MIG from automatically applying new a VM configuration to existing VMs. Formore information, seeCheck your group's update policy type.

Then use the gcloud CLI or REST to update your MIG'sconfiguration and to apply the latest configuration to specific VMs in thegroup or to all VMs in the group.

gcloud compute instance-groups managed set-instance-templateINSTANCE_GROUP_NAME \    --template=INSTANCE_TEMPLATE

gcloud compute instance-groups managed update-instancesINSTANCE_GROUP_NAME \--instancesINSTANCE_NAMES \    --most-disruptive-allowed-actionDISRUPTION_LEVEL \    --minimal-actionDISRUPTION_LEVEL

gcloud compute instance-groups managed update-instancesINSTANCE_GROUP_NAME \--all-instances \    --most-disruptive-allowed-actionDISRUPTION_LEVEL \    --minimal-actionDISRUPTION_LEVEL

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

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}

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}

After you make a request, you cancheck the statusto verify that the update is complete.

Control the disruption level during selective updates

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

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

  • To limit disruption as much as possible, set the minimal action toNONE. If your update requires a more disruptive action,Compute Engine performs the necessary action to execute theupdate.
  • To apply a more disruptive action than is strictly necessary, set theminimal action toRESTART orREPLACE. For example,Compute Engine does not need to restart a VM to change itsmetadata. But if your application reads instance metadata only when a VMis restarted, you can set the minimal action toRESTART in order to pickup metadata changes.

• Most disruptive allowed action: Use this option to prevent an update ifit requires more disruption than you can afford. If your update requires amore disruptive action than you set with this flag, the update request fails.For example, if you set the most disruptive allowed action toRESTART, thenan attempt to update the boot disk image fails because that update requiresinstance recreation, a more disruptive action than a restart.

When updating selected VMs, both of these options accept the followingvalues:

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

When you selectively update VMs, the following defaults apply:

• The default minimal action isNONE, which limits disruption as much aspossible.
• The default most disruptive allowed action isREPLACE. If you cannottolerate such disruption, set the most disruptive allowed action to be lessdisruptive.

What's next

• Learn aboutViewing info about MIGs and managed VMs.
• Learn aboutCreating instance templates.
• Learn how to use image families and a rolling replace toupdate the OS imageon all VMs in a MIG.