Selectively apply VM configuration updates in a MIG

This document describes how to selectively apply configuration updates to the virtual machine (VM) instances in a managed instance group (MIG).

Compute Engine maintains the VMs in a MIG based on the configuration components that you use: instance template, optional all-instances configuration, and optional stateful configuration.

Whenever you update a MIG's VM configuration by changing those components, Compute Engine automatically applies your updated configuration to new VMs that are added to the group.

To apply an updated configuration to existing VMs, you can set up a selective update–also known as a "opportunistic" update type. This type of update 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 all VMs immediately.

Alternatively, if you want to automate the rollout of a new configuration to all or to a random subset of the VMs in a MIG, see Automatically apply VM configuration updates in a MIG. To help you decide, see Methods to apply a new configuration to existing VMs.

Before you begin

  • If you haven't already, then set up authentication. Authentication is the process by which your identity is verified 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, then initialize it by running the following command: 

      gcloud init
    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, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate 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 prevent the MIG from automatically applying new a VM configuration to existing VMs. For more information, see Check your group's update policy type.

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

gcloud

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

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

Apply configuration to specific VMs

To apply the updated configuration to specific VMs, use the update-instances command with the --instances flag.

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

Apply configuration to all VMs

To apply the updated configuration to all VMs, use the update-instances command with the --all-instances flag.

gcloud compute instance-groups managed update-instances INSTANCE_GROUP_NAME \
    --all-instances \
    --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 VMs 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

REST

To set up a new instance template for your group, call the patch method on a zonal or regional MIG and update the versions.instanceTemplate field. To avoid automatically rolling out the new template to all VMs 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",
  }]
}

Apply configuration to specific VMs

To apply the updated configuration to specific VMs, call the applyUpdatesToInstances method for your zonal or regional MIG and specify a list of VMs in the request.

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
}

Apply configuration to all VMs

To apply the updated configuration to all existing VMs, set the allInstances field to true:

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 VMs 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.

Control 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 VMs, 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 VMs, 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