Updating Managed Instance Groups

This page describes how to make updates to your managed instance groups. To learn about managed instance groups, read the Instance Groups documentation.

A managed instance group contains one or more virtual machine instances that are controlled using an instance template. To update instances in a managed instance group, you can make update requests to the group as a whole, using the Managed Instance Group Updater feature.

The Managed Instance Group Updater allows you to easily deploy new versions of software to instances in your managed instance groups, while controlling the speed of deployment, the level of disruption to your service, and the scope of the update. The Updater offers two primary advantages:

  • The rollout of an update happens automatically to your specifications, without the need for additional user input after the initial request.
  • You can perform partial rollouts which allows for canary testing.

By allowing new software to be deployed inside an existing managed instance group, there is no need for you to reconfigure the instance group or reconnect load balancing, autoscaling, or autohealing each time new version of software is rolled out. Without the Updater, new software versions must be deployed either by creating a new managed instance group with a new software version, requiring additional set up each time, or through a manual, user-initiated, instance-by-instance recreate. Both of these approaches require significant manual steps throughout the process.

Before you begin

Starting a basic rolling update

A rolling update is an update that is gradually applied to all instances in an instance group until all instances have been updated. You can control various aspects of a rolling update, such as how many instances can be taken offline for the update, how long to wait between updating instances, whether the update affects all or just a portion of instances, and so on.

Here are things to keep in mind when making a rolling update:

  • Updates are intent based. When you make the initial update request, the API returns a successful response to confirm that the request was valid but that does not indicate that the update was successful. You will need to check the status of the managed instance group to determine if your update was deployed successfully.

  • The Instance Group Updater API is a declarative API. The API expects a request to specify the desired post update configuration of the managed instance group, rather than an explicit function call.

  • The Updater feature supports up to two instance template versions in your managed instance group. This means that you can specify two different instance template versions for your managed instance group, which is useful for performing canary updates.

To start a basic rolling update where the update is applied to 100% of the instances in the group, follow the instructions below.

Console

  1. Go to the Instance groups page in the Cloud Platform Console.

    Go to the Instance groups page

  2. Select the instance group you want to update.
  3. At the top of the page, click Rolling update.
  4. Under Template, pull down the drop down menu and select the new template to update to.
  5. For the target size, enter 100% to update all instances.
  6. Optionally, you can toggle configuration options like whether the update is proactive (the group actively replaces instances) or opportunistic (the group does not actively replace instances but applies the update when instances are replaced from other means). You can also supply max surge, max unavailable options, and minimum wait time.
  7. Click Update to start the update.

gcloud

Using the gcloud tool, run the rolling-action start-update command:

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP] \
    --version template=[INSTANCE_TEMPLATE] [--zone [ZONE] | --region [REGION]]

where:

  • [INSTANCE_GROUP] is the name of the instance group to update.
  • [INSTANCE_TEMPLATE] is the new instance template to update the instance group to.
  • Either a [ZONE] or [REGION] for this instance group. If the instance group is a zonal instance group, provide the zone. If it is regional, provide the region.

API

In the API, make a PATCH request to the following URL:

https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[MANAGED_INSTANCE_GROUP_NAME]

If the instance group is a regional managed instance group, replace zones/[ZONE] with regions/[REGION].

The request payload contains:

  • The instance template to update the group to.
  • An update policy for the request and other update options.

The following is the minimal configuration necessary for initiating an update in the API. If you don't specify otherwise, the maxSurge and maxUnavailable properties will be set to 1, which means that the Updater will only make 1 instance unavailable at any given time, and will only create 1 additional instance above the target size of the instance group during the update. The request will update 100% of instances to the new instance template.

For example:

{
  "instanceTemplate": "global/instanceTemplates/example-template",
  "updatePolicy": {
    "type": "proactive"
   }
 }

After you make a request, you can monitor the update to know when the update has finished.

Configuring options for your update

For more complex updates, you can configure additional options for a specific update request. These options are described below.

Max surge

Set the maxSurge property to allow the Updater to temporarily create new instances above the targetSize during the update. For example, if you set maxSurge to 5, the managed instance group will create up to 5 new instances above your target size, with the new instance template. Setting a higher maxSurge value will speed up your update, at the cost of additional instances, which are billed according to the Compute Engine price sheet. If you do not set the maxSurge value, the default value of 1 max surge instance is used.

This option is recognized only when configured with the REPLACE minimal action, but is not supported with the RESTART action setting. You can specify either a fixed number, or specify a percentage if the managed instance group has 10 or more instances. If you set a percentage, the updater will round up the number of instances if necessary.

maxSurge will only work if you have enough quota or resources to support the additional resources.

Max unavailable

Set the maxUnavailable configuration so that only a certain number of instances are unavailable at any time during the update. For example, if you set maxUnavailable to 5, then only 5 instances will be taken offline for updating at a time. Use this parameter to control how disruptive the update is to your service and to control the rate at which the update is deployed.

This number also includes any instances that are unavailable for other reasons. For example, if the instance group is in the process of being resized up, instances in the middle of being created might be unavailable; these instances would count towards the maxUnavailable number. You can specify either a fixed number, or specify a percentage if the managed instance group has 10 or more instances. If you set a percentage, the updater will round down the number of instances, if necessary.

If not specified, the default value of 1 max unavailable instance is used.

Minimum wait time

Set the minReadySeconds property to control the amount of time the Updater service should wait before considering a newly created or restarted instance as updated. The timer starts after a successful health check. Use this feature to control the rate at which the update is deployed. The maximum value for the minReadySeconds property is 3600 seconds (1 hour).

Minimal action

Set the minimal action property to control the minimum action that Updater must perform to update the instances in the group. For example, if you set REPLACE as the minimum action, then all instances that are affected will be deleted and replaced with a new instance, whether or not it is necessary.

Setting a minimal action guarantees that the updater will perform that action, at a minimum. However, if the updater determines that the minimal action you specify is not enough to perform the update, it might perform a more disruptive action. For example, if you set RESTART as the minimal action, the updater will attempt to restart instances to apply the update. However, if the update requires a more disruptive action, the updater will perform that action. Changing an instance's OS, for example, cannot be done by restarting the instance so the updater will replace the instances in the instance group with new VM instances.

Applicable actions are REPLACE or RESTART:

  • RESTART: Restarts the instance (performs a stop and start request). Note that if your update request requires that the instance be replaced to pick up the changes (for example, changing the image would require that the instance is deleted and replaced), will be forced to perform REPLACE.

  • REPLACE: Deletes the existing instance and creates a new instance from the target template. The Updater creates a brand new instance with all new instance properties, such as new internal and external IP addresses.

The following diagram visualizes how these options affect your instances.

Diagram explaining how different updater options affect your request

Additional update examples

Here are some command-line examples with common configuration options.

Perform a rolling update of all virtual machine instances, but create up to 5 new instances above the target size at a time

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
    --version template=[NEW_TEMPLATE] --max-surge 5 [--zone [ZONE] | --region [REGION]]

Perform a rolling update with at most 3 unavailable machines and a minimum wait time of 3 minutes before marking a new instance as available

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
    --version template=[NEW_TEMPLATE] --min-ready 3m \
    --max-unavailable 3 [--zone [ZONE] | --region [REGION]]

For example, if you have 1000 instances and you ran this command, the updater will create up to 100 new instances before it starts to remove instances running the previous instance template.

Perform a rolling update of all virtual machine instances, but create up to 10% new instances above the target size at a time

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
    --version template=[NEW_TEMPLATE] --max-surge 10% [--zone [ZONE] | --region [REGION]]

Starting a canary update

The Instance Group Updater feature allows you to perform canary updates, so that you can test your updates on a random subset of instances before fully committing to the update.

A canary update is an update that is applied to a partial number of instances in the instance group. Canary updates let you test new features or upgrades on a subset of instances, instead of rolling out a potentially disruptive update to all your instances. If an update is not going well, you only need to roll back a small number of instances, minimizing the disruption for your users. From the perspective of the server, a canary update is the same as a standard rolling update, except that the number of instances that should be updated is less than the total size of the instance group.

For a canary update:

  • You can specify up to two instance template versions. For example, you can specify that 20% of your instances are created based on new-instance-template while the rest of the instances continue to run on old-instance-template. You cannot specify more than two instance templates at a time.

  • You must always specify a target size (targetSize) for the canary version. You cannot specify two instance template versions and omit the target size for the canary version.

To start a canary update, make an update request with the new instance template and provide a targetSize for the new template to indicate how many instances should be updated. You can express targetSize as either a fixed number or a percentage if the managed instance group has 10 or more instances. If you set a percentage, the number of instances is rounded up, if necessary.

Console

  1. Go to the Instance groups page in the Cloud Platform Console.

    Go to the Instance groups page

  2. Select the instance group you want to update.
  3. At the top of the page, click Rolling update.
  4. Click Add template and choose the new instance template to canary.
  5. Under Target size, enter the percentage or fixed number of instances you want to use to canary the new instance template.
  6. Optionally, you can toggle configuration options like whether the update is proactive (the group actively deletes and replaces instances) or opportunistic (the group does not actively replace instances but applies the update when instances are created from other means). You can also supply max surge, max unavailable options, and minimum wait time.
  7. Click Update to start the update.

gcloud

Using the gcloud command-line tool, provide both the current template and the new template to explicitly express how many instances should use each template:

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
    --version template=[CURRENT_TEMPLATE] \
    --canary-version template=[NEW_TEMPLATE],target-size=[SIZE] \
    [--zone [ZONE] | --region [REGION]]

where:

  • [CURRENT_TEMPLATE] is the current template that the instance group is running.
  • [NEW_TEMPLATE] is the new template you want to canary.
  • [SIZE] is the number or percentage of instances you want to apply this update to. You must apply the target-size property to the --canary-version template. You can only set a percentage if the instance group contains 10 or more instances.
  • Either a [ZONE] or [REGION] for this instance group. If the instance group is a zonal instance group, provide the zone. If it is regional, provide the region.

For example, the following command performs a canary update that rolls out my-template-b to 10% of instances in the instance group:

gcloud alpha compute instance-groups managed rolling-action start-update my-ig1 \
        --version template=my-template-A --canary-version template=my-template-B,target-size=10%

API

In the API, make a PATCH request to the following URI:

https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

The request payload should contain both the current instance template and the new instance template that you want to canary. For example:

{
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/[NEW_TEMPLATE]",
   "targetSize": {
    "[percent|fixed]": [NUMBER|PERCENTAGE] # Use `fixed` for a specific number of instances
   }
  },
  {
   "instanceTemplate": "global/instanceTemplates/[CURRENT_TEMPLATE]"
  }
 ]
}

where:

  • [NEW_TEMPLATE] is the name of the new template you want to canary.
  • [NUMBER|PERCENTAGE] is the fixed number or percentage of instances to canary this update. You can only set a percentage if the instance group contains 10 or more instances. Otherwise, provide a fixed number instead.
  • [CURRENT_TEMPLATE] is the name of the current template that the instance group is running

Rolling forward a canary update

After running a canary update, you can decide if you want to commit the update to 100% of the instance group or roll back.

Console

  1. Go to the Instance groups page in the Cloud Platform Console.

    Go to the Instance groups page

  2. Select the instance group you want to update.
  3. At the top of the page, click Rolling update.
  4. Under Template, update the target size of the canary template to 100% to roll forward the template to all your instances. Alternatively, you can replace the primary template with the canary template and set the target size to 100%. Then, you can remove the second template field altogether.
  5. Click Update to start the update.

gcloud

If you want to commit to your canary update, roll forward the update by making the same update request but setting only version and omitting --canary-version. Using the gcloud command-line tool:

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \ --version template=[NEW_TEMPLATE] [--zone [ZONE] | --region [REGION]]

API

In the API, make a PATCH request to the following URI:

https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

In the request body, specify the new instance template as a version and omit the old instance template from your request body. Omit the target size specification to roll the update out to 100% of instances. For example, your request body would look like this:

{
"versions": [
   {
   "instanceTemplate": "global/instanceTemplates/[NEW_TEMPLATE]" # New instance template
   }
 ]
}

Replace [NEW_TEMPLATE] with the name of the new instance template you want to roll forward.

Starting an opportunistic or proactive update

By default, updates made using the gcloud command-line tool are proactive and updates initiated in the API are opportunistic.

For proactive updates, Compute Engine actively schedules actions to apply the requested updates to instances as necessary. In many cases, this often means deleting and recreating instances proactively.

Alternatively, you can choose to perform an opportunistic update, if a proactive update is potentially too disruptive. An opportunistic update is only applied when new instances are created by the managed instance group. This typically happens when the managed instance group is resized either by another service, such as an autoscaler, or manually by a user. Compute Engine does not actively initiate requests to apply 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 managed instance group 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.

To choose whether an update is opportunistic or proactive, set the type property to OPPORTUNISTIC or PROACTIVE using either the gcloud command-line tool or the API.

Console

  1. Go to the Instance groups page in the Cloud Platform Console.

    Go to the Instance groups page

  2. Select the instance group you want to update.
  3. At the top of the page, click Rolling update.
  4. Under Template, choose a template to update your instance group to and select a target size for the template.
  5. Under Update mode, choose between either an opportunistic or proactive update.
  6. Click Update to start the update.

gcloud

Using the gcloud command-line tool:

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
    --version template=[INSTANCE_TEMPLATE] \
    --type [opportunistic|proactive] [--zone [ZONE] | --region [REGION]]

API

In the request payload to start an update, include the type property in your updatePolicy:

{
"updatePolicy": {
  "type": "PROACTIVE" # Performs a proactive update
},
"versions": [{
  "instanceTemplate": "global/instanceTemplates/[NEW_TEMPLATE]",
  }]
}

where [NEW_TEMPLATE] is the name of the new template you want to canary. If you want an opportunistic update, replace PROACTIVE with OPPORTUNISTIC.

Performing a rolling replace or restart

Alternatively, you can use the restart or replace commands to perform a rolling restart or a rolling replace of VM instances in the managed instance group. Similar to the start-update command, you can specify any of the configuration options for a restart or a replace. A rolling restart or replace does not change anything about the instance group, including the instance template. It simply refreshes the instances in the group using the method you choose.

There are many reasons why you might want a rolling replace or a rolling restart. For example, you might want to refresh your VM instances from time to time to:

  • Clear up memory leaks.
  • Restart your application so it can run from a fresh machine.
  • Force a periodic replace as a best practice to test your VMs.
  • Update your VM's operating system image or rerun startup scripts to update your software.

To perform a replace where all instances are deleted and replaced with new instances:

Console

  1. Go to the Instance groups page in the Cloud Platform Console.

    Go to the Instance groups page

  2. Select the instance group you want to update.
  3. At the top of the page, click Rolling restart/replace.
  4. Choose whether you want to restart or replace your instances. Restarting performs the stop and start methods on the instances, while a replace will actively delete and create instances.
  5. Optionally, you can toggle configuration options like max surge, max unavailable options, and minimum wait time.
  6. Click Restart or Replace button to start the update.

gcloud

gcloud alpha compute instance-groups managed rolling-action replace [INSTANCE_GROUP]

This command replaces all instances in the managed instance group, one at a time. If a full replace is too disruptive, you can specify a rolling restart instead, which does not delete any instances and just restarts each instance.

gcloud alpha compute instance-groups managed rolling-action restart [INSTANCE_GROUP]

You can further customize each of these commands with the same options available for updates (for example: maxSurge, maxUnavailable, min-ready).

API

In the API, make a PATCH request for the group and set a proactive updatePolicy where the minimalAction is either RESTART or REPLACE depending whether you want to perform a rolling replace, where each instance is deleted and replaced with a new instance, or a rolling restart, where each instance is stopped and restarted. In both cases of RESTART and REPLACE, you must always provide a versions.instanceTemplate and a versions.name property (for example, v2) to trigger the action.

A rolling replace might look like the following:

PATCH https://www.googleapis.com/compute/alpha/projects/myproject/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

{
 "updatePolicy": {
  "minimalAction": "REPLACE",
  "type": "PROACTIVE"
 },
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/example-template",
   "name": "v2"
  }
 ]
}

For a rolling restart:

PATCH https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

{
 "updatePolicy": {
  "minimalAction": "RESTART",
  "type": "PROACTIVE"
 },
 "versions": [
  {
   "instanceTemplate": "global/instanceTemplates/example-template",
   "name": "v2"
  }
 ]
}

Additional replace/restart examples

Perform a rolling restart of all virtual machines, two at a time

This command restarts all virtual machines in the instance group, two at a time. Notice that no new instance template is specified.

gcloud alpha compute instance-groups managed rolling-action restart [INSTANCE_GROUP_NAME] \
    --max-unavailable 2 [--zone [ZONE] | --region [REGION]]

Rolling restart all VMs as quickly as possible

gcloud alpha compute instance-groups managed rolling-action restart [INSTANCE_GROUP_NAME] \
    --max-unavailable 100% [--zone [ZONE] | --region [REGION]]

Rolling replace all VMs as quickly as possible

gcloud alpha compute instance-groups managed rolling-action replace [INSTANCE_GROUP_NAME]  \
    --max-unavailable 100% [--zone [ZONE] | --region [REGION]]

Updating a regional managed instance group

A regional managed instance group contains virtual machine instances spread across multiple zones within a region, as opposed to zonal managed instance groups, which only contain instances in one zone. Regional managed instance groups give you the ability to distribute your instances across more than one zone to improve your application's availability and to support extreme cases where one zone fails or an entire group of instances stops responding.

Updating a regional managed instance group using the Instance Group Updater feature is same as performing an update on a zonal managed instance group, with a few exceptions described below. When you initiate an update to a regional instance group, the Updater will always update instances proportionally and evenly across each zone; it is not possible to choose which instances in which zones are updated first or to update instances in only one zone.

Differences between updating a regional versus zonal managed instance group

Before you initiate an update to a regional managed instance group, you should be aware that there are a number of things that behave differently than for zonal managed instance groups:

  • The default update parameters for regional managed instance group is to set maxUnavailable=0 and maxSurge=3. This is to ensure that no VM instances are taken down accidentally (maxUnavailable set to 0) but the update can still move forward by allowing one extra VM instance per zone (maxSurge set to 3).

  • If you are using fixed numbers when specifying an update, the fixed number must be either 0 or larger than or equal to 3. You cannot set an update parameter with 2 or 1 as its value. This is because regional managed instance groups are distributed over regions with 3 zones. For example, to specify maxSurge, you must use either 0 or a number larger than or equal to 3 so the Updater can create 1 additional instance per zone.

Using a fixed number or a percentage in update requests

If you specify a fixed number in your update requests, the number you specify is divided by the number of zones in the regional managed instance group and distributed evenly. For example, if you specify maxSurge=10, then the Updater will divide 10 across the number of zones in the region and create new instances based on that number. If the number of instances does not divide evenly across zones, the Updater will add the additional instances to a random zone. So, for 10 instances across three zones, two of the zones will get 3 instances and one zone will get 4 instances. The same logic is applied to the maxUnavailable and the targetSize parameter for canary updates.

You can only specify a percentage if your managed instance group contains 10 or more VM instances. Percentages are handled slightly differently depending on the situation:

  • If you specify a percentage of VM instances for a canary update, the Updater attempts to distribute the instances evenly across zones. The remainder is rounded either up or down in each zone but the total difference will not be more than 1 VM instance per group. For example, for a managed instance group with 10 instances and a target size percentage of 25%, the update will be rolled out to 2 to 4 VM instances.

  • If you specify a percentage for update options like maxSurge and maxUnavailable, the percentages are rounded independently per zone. The same rules that apply to updating zonal managed instance groups apply here.

Monitoring rolling updates

After you initiate a rolling update, it can take some time for the update to finish. You can monitor the state of the update by getting a list of instances that are part of the managed instance group. The Compute Engine API returns the instance status along with a list of instances.

Console

You can monitor a rolling update for a group by going to the details page of the specific instance group.

  1. Go to the Instance groups page in the Cloud Platform Console.

    Go to the Instance groups page

  2. Select the instance group you want to update. The overview page for the instance group shows the template that each instance is using.
  3. To dive into the details, click on Details tab.

The Details page shows the current and target number of instances being updated for each instance template and also displays the update parameters.

gcloud

gcloud alpha compute instance-groups managed list-instances [INSTANCE_GROUP_NAME] [--zone [ZONE] | --region [REGION]]

gcloud returns a response with a list of instances in the instance group and their respective statuses. For example:

NAME               ZONE           STATUS   ACTION    INSTANCE_TEMPLATE  LAST_ERROR
vm-instances-9pk4  us-central1-f           CREATING  my-new-template
vm-instances-h2r1  us-central1-f           DELETING  my-old-template
vm-instances-j1h8  us-central1-f  RUNNING  NONE      my-old-template
vm-instances-ngod  us-central1-f  RUNNING  NONE      my-old-template

API

In the API, make a POST request to the following URI:

POST https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]/listManagedInstances

If the instance group is a regional managed instance group, replace zones/[ZONE] with regions/[REGION].

The API returns a list of instances for the group and their respective status and current action.

{
 "managedInstances": [
  {
   "instance": "https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-j701",
   "id": "4251656203855893170",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/global/instanceTemplates/[INSTANCE_TEMPLATE_NAME]",
   "currentAction": "REFRESHING"
  },
  {
   "instance": "https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-prvp",
   "id": "5317605642920955957",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/global/instanceTemplates/[INSTANCE_TEMPLATE_NAME]",
   "currentAction": "REFRESHING"
  },
  {
   "instance": "https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-pz5j",
   "currentAction": "DELETING"
  },
  {
   "instance": "https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instances/vm-instances-w2t5",
   "id": "2800161036826218547",
   "instanceStatus": "RUNNING",
   "instanceTemplate": "https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/global/instanceTemplates/[INSTANCE_TEMPLATE_NAME]",
   "currentAction": "REFRESHING"
  }
 ]
}

Group status and pending and current actions

An instance's current status is described by the instanceStatus field of the instance. If the instance is undergoing some type of change, the currentAction field will also be populated to help you track the status of updates. When the instance is successfully updated, the instanceStatus field will reflect the instance's current state. To see a list of valid instanceStatus fields, see the documentation for Checking Instance Status.

If an instance is undergoing some type of change, the currentAction field will be populated with one of the following statuses. Otherwise, the currentAction field will be empty.

  • CREATING: The instance is in the process of being created.
  • CREATING_WITHOUT_RETRIES: The instance is being created without retries; if the instance fails to be created on the first try, the managed instance group will not try to repalce the instance again.
  • DELETING: The instance is in the process of being deleted.
  • RECREATING: The instance was deleted and is being replaced.
  • RESTARTING: The instance is in the process of being restarted using the stop and start methods.
  • REFRESHING: The instance is being removed from its current target pools and being readded to the list of current target pools (this list might be the same or different from existing target pools).

At the managed instance group level, Compute Engine populates a field called pendingActions that describes the number of instances currently awaiting a specific action. For example, the pendingActions field might return a count of pendingActions that say:

CREATING: 3
DELETING: 3
RECREATING: 2
RESTARTING: 1

This indicates that there are three instances that are pending deletion, two instances that are going to be replaced, one instance that will be restarted, and three instances that will be created.

Rolling back an update

There is no explicit command for rolling back an update to a previous version but if you decide that you want to roll back an update (either a fully committed or canary update), you can do so by making a new update request and passing in the instance template that you want to roll back to.

For example, the following command rolls back an update as fast as possible:

gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
    --version template=[OLD_INSTANCE_TEMPLATE] --max-unavailable 100% [--zone [ZONE] | --region [REGION]]

Replace [OLD_INSTANCE_TEMPLATE] with the name of the old instance template you want to roll back to.

In the API, make a PATCH request to the following URI:

https://www.googleapis.com/compute/alpha/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP_NAME]

If the instance group is a regional managed instance group, replace zones/[ZONE] with regions/[REGION].

In the request body, specify the old instance template as a version:

{ "updatePolicy":
  {
    "maxUnavailable":
    {
      "percent": 100
    }
  },
 "versions": [
    {
      "instanceTemplate": "global/instanceTemplates/[OLD_TEMPLATE]" # Old instance template
    }
   ]
}

The Instance Group Updater service treats this as a regular update request so all of the update options described in this document can be specified with your request.

Controlling the speed of an update

By default, when you make an update request, the service performs the update as fast as possible. If you aren't sure you want to apply an update fully or are tentatively testing your changes, you can apply the update slowing using the following methods:

  1. Start a canary update rather than a full update.
  2. Set a large minReadySeconds value. Setting this value causes the service to wait this number of seconds before considering the instance successfully updated and proceeding to the next instance.
  3. Set a low maxUnavailable and maxSurge value. This ensures that only a minimal number of instances are updated at a time.

You can also use a combination of these parameters to control the rate of your update.

Stopping an update

There is no explicit method or command to stop an update. You can change an update from proactive to opportunistic and if the managed instance group is not being resized by other services like autoscaler, the change to opportunistic will effectively "stop" the update.

To change an update from proactive to opportunistic, run the following command:

gcloud alpha instance-groups managed rolling-action stop-proactive-update [INSTANCE_GROUP_NAME] \
    [--zone [ZONE] | --region [REGION]]

If you decide you want to stop the update completely after converting it from proactive to opportunistic, you can stop it using these steps:

  1. Make a request to determine how many instances have been updated.

    gcloud alpha compute instance-groups managed list-instances [INSTANCE_GROUP_NAME] \
        [--zone [ZONE] | --region [REGION]]

    The gcloud tool returns a response with a list of instances in the instance group and their current statuses:

    NAME               ZONE           STATUS   ACTION    INSTANCE_TEMPLATE  LAST_ERROR
    vm-instances-9pk4  us-central1-f  RUNNING  NONE      my-new-template
    vm-instances-j1h8  us-central1-f  RUNNING  NONE      my-new-template
    vm-instances-ngod  us-central1-f  RUNNING  NONE      my-old-template
    

    In this example, two instances have already been updated.

  2. Next, make a request to perform a new "update" but pass in the number of instances that have already been updated as the target size:

    gcloud alpha compute instance-groups managed rolling-action start-update [INSTANCE_GROUP_NAME] \
        --version template=my-old-template \
        --canary-version template=my-new-template,target-size=2 \
        [--zone [ZONE] | --region [REGION]]

    To the Updater service, this update appears "complete", so no other instances are updated, effectively stopping the update.

Relationship between instanceTemplate properties for a managed instance group

A managed instance group could potentially have up to two instanceTemplate properties: a top-level instanceTemplate property, and an instanceTemplate for performing a canary update. For example, the following managed instance group has two instance template properties because it is in the middle of a canary update:

..[snip]..
instanceGroup: https://www.googleapis.com/compute/alpha/projects/myproject/zones/us-east1-b/instanceGroups/example-instance-group
instanceTemplate: https://www.googleapis.com/compute/alpha/projects/myproject/global/instanceTemplates/example-template
versions:
- instanceTemplate: https://www.googleapis.com/compute/alpha/projects/myproject/global/instanceTemplates/example-template-2
  targetSize:
    calculated: 3
    fixed: 3
- instanceTemplate: https://www.googleapis.com/compute/alpha/projects/myproject/global/instanceTemplates/example-template
zone: https://www.googleapis.com/compute/alpha/projects/myproject/zones/us-east1-b
..[snip]..

In general, the top-level instanceTemplate property reflects what the Updater considers the "current" template. So:

  • If an instance group does not have the versions field set, then the instanceTemplate property reflects the current instance template being used by the instance group manager.

  • If there is a versions field set, the instanceTemplate property reflects the non-canary template. That is, it reflects the template that has no targetSize set because the Updater assumes that the template with the target size set is a canary template that is still being tested.

Feedback and Questions

We welcome your feedback and questions! Please send your questions to the Alpha discussion group.

What's next

Send feedback about...

Compute Engine Documentation