Instance Group Manager API

The Google Compute Engine Instance Group Manager API creates and manages pools of homogeneous Compute Engine virtual machine instances from a common instance template.

• The instance template defines the configuration options for your virtual machines, including the machine type, image, zone, and other settings.
• The instance group manager creates and deploys the specified number of those machines into a new instance group.
• The instance group contains the instances and can be targeted by the load balancing or autoscaler services.

Managed instance groups differ from regular instance groups in the following ways:

• They contain a number of identical Compute Engine instances. Regular instance groups only require that instances in the group live within the same zone.
• The instance group manager ensures that all instances in the group are in the RUNNING state, and recreates any that are not.
• The number of instances in the group can be updated using the resize method. This method will create new instances according to the provided template, or delete instances to meet the specified number.
• The instances in a managed instance group can only be updated through the Instance Group Manager API. They can not be updated through the regular Instance Group API.

The Instance Group Manager API is recommended for users who need a service to create and manage a large number of homogeneous resources that occasionally require simple tasks such as resizing the number of instances, or updating their attributes.

Getting started

To get started with the Instance Group Manager API, you need to enable the necessary APIs. You might also want to install the command line interface and download a client library.

Enable the Compute Engine API

The Instance Groups service requires access to Compute Engine resources. You must first enable the Compute Engine API before enabling Instance Groups.

Enable the Compute Engine API

Enable the Instance Groups and Instance Group Manager API

Next, you must enable the Instance Groups API in the Google Developers Console. If you have multiple projects in the Google Developers Console, make sure that you enable the Instance Groups API and the Compute Engine API in the same project.

Enabling the Instance Groups API automatically enables the Instance Group Manager API as well.

Enable the Instance Groups API

Install the command line interface

If you'll be using the command line to interact with the Instance Groups service, you must first:

1. Install the gcloud tool.

2. Enable preview features in the gcloud tool:

   $ gcloud components update preview
   

3. Tell the command line interface which Google Developers Console project to use:

   $ gcloud config set project PROJECT
   

To find the value of PROJECT, visit the Developers Console and refer to the Project ID column.

This document shows examples using the command line interface. For information on the REST API, refer to the API reference.

The REST API and Google APIs Explorer

All operations in the Instance Group Manager API can also be accomplished through the REST API. Our reference documentation embeds the Google APIs Explorer, which allows you to authenticate, send requests, and receive responses for each method from the specific documentation page.

Download a client library

Google provides client libraries for a number of languages. To learn more, visit the Google APIs Client Libraries documentation.

Quotas

You may send up to 50,000 requests to the Instance Group Manager API per day. Please contact us if you require additional quota.

The Instance Group Manager resource

An Instance Group Manager resource takes the form of the JSON below:

{
  "kind": string,
  "name": string,
  "id": string,
  "fingerprint": bytes,
  "creationTimestamp": string,
  "description": string,
  "selfLink": string,
  "currentSize": integer,
  "targetSize": integer,
  "instanceTemplate": string,
  "resourceView": string,
  "targetPools": {
    "items": [
      string
    ]
  },
  "baseInstanceName": string
}

Where:

• kind is always replicapool#replicaPool.
• name is the user-assigned name for this instance group manager. The name must conform to RFC1035. Accepted characters include lowercase letters, numbers, and hyphens (-).
• id is the system-assigned identifier.
• fingerprint is the system-computed hash of this resource.
• creationTimestamp is the time the manager was created, using RFC3339 format.
• description is an optional descriptive string for the manager.
• selfLink is the system-defined fully qualified URL for the manager.
• currentSize is the number of currently running Compute Engine instances.
• targetSize is the desired number of Compute Engine instances. This may differ from currentSize if instances have not yet completed their startup or have not yet been added to the specified target pools.
• instanceTemplate is the full URL to the instance template from which new instances will be created.
• resourceView is the full URL to the instance group that was created by the instance group manager. Note that instance group is the new name for resource view and you may see either term used until the renaming is complete.
• targetPools is a list of URLs to existing Target Pool resources. All instances in the managed instance group are added to these target pools.
• baseInstanceName is a root string used to name instances in this group. New instances will use the base instance name plus a hyphen and a four-character string as their name.

Creating a managed instance group

Before creating an instance group manager, you need a valid instance template. Refer to the Instance Templates page for information.

Once you have an instance template, to create an instance group manager with gcloud preview, use the managed-instance-groups create sub-command:

gcloud preview managed-instance-groups --zone ZONE create GROUP \
  --base-instance-name BASE_INSTANCE_NAME \
  --size SIZE \
  --template TEMPLATE \
  [--target-pool [TARGET_POOL ...]]

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name to give this managed instance group. The name must conform to RFC1035. Accepted characters include lowercase letters, numbers, and hyphens (-).

--base-instance-name BASE_INSTANCE_NAME

[Required] The base name to use for the Compute Engine instances that will be created in the managed instance group. A hyphen followed by a random four-character string will be appended to the base name for each new instance that is created.

--size SIZE

[Required] Initial number of instances in the managed instance group.

--template TEMPLATE

[Required] The name of the Compute Engine instance template resource to be used.

--target-pool [TARGET_POOL ...]

[Optional] The Compute Engine target pools to add the instances to. Target pools must be specified by name, not by URL. For example: --target-pools target-pool-1 target-pool-2

For a full list of parameters, refer to the gcloud preview reference, or enter gcloud preview managed-instance-groups create --help on the command line.

The create operation is considered complete once all of the instances have been created and added to their instance groups and target pools (if specified).

Retrieving managed instance groups

To get information about a specific managed instance group with gcloud preview, use the managed-instance-groups describe sub-command:

$ gcloud preview managed-instance-groups --zone ZONE describe GROUP

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

To list all managed instance groups within a project, use the managed-instance-groups list sub-command:

$ gcloud preview managed-instance-groups --zone ZONE list

Updating the instance template

You can update the instance template for a managed instance group in two ways:

1. Use the set-template method, which applies the new instance template to any new or recreated instances. The new template does not affect existing instances. If you use this method, it could cause your managed instance group to contain non-identical instances.

   For more information, see Applying updates to new instances.

2. [Alpha] Use the Instance Group Updater service, which applies a rolling update of the new template to all existing instances and also applies the new instance template to any new or recreated instances. This method gradually recreates existing instances one at a time with the new template, ensuring that the instances eventually will be identical.

   For more information, see Applying rolling updates using the Updater service.

If you want full control of how your new template affects your instances, you can use the set-template method so the update is only selectively applied to new instances. However, if you just want the template to apply to all existing and new instances, we recommend that you use the Instance Group Updater service.

Applying updates to new instances

The set-template method allows you to apply updates to new instances but does not apply the updates to existing instances unless those instances are manually recreated. This allows you to control exactly which instances should be updated but could cause your Instance Group to contain non-identical instances.

To use the set-template method to update a template, pass the new template to the managed-instance-groups set-template sub-command:

$ gcloud preview managed-instance-groups --zone ZONE set-template GROUP \
    --template TEMPLATE

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

--template TEMPLATE

[Required] The name of the new instance template to use. Accepts only the name of the template; do not pass the fully qualified URL of the template resource.

Applying rolling updates using the Updater service

You can apply a rolling update to your managed instance group using the Instance Group Updater service, so that new templates are applied to both existing and new instances. A rolling update gradually recreates your existing instances with the new template, at a defined rate. You can control how fast the update applies, how long to wait between updates, whether you want to automatically pause the update after a few instances are done, and other settings.

• Sign up
• Starting an update
• Getting and listing rolling updates
• Pausing a rolling update
• Rolling back an update
• Continue a rolling update
• Canceling a rolling update

Sign up

1. The rolling update feature is currently in Alpha and requires that you request access to use it.

   Request access

2. After you have been given access to the feature, you can enable the API in the Google Developers Console.

   Enable the Updater API

Starting an update

To start a rolling update in gcloud, pass in a new template to the rolling-updates start sub-command. By default, a rolling update applies to one instance at a time, and spends at least 10 seconds on each instance before moving to the next one. You can choose to override these settings as necessary for your needs.

For example, the following command starts a rolling update for a group named example-group, using a new template called example-template:

$ gcloud preview rolling-updates --zone us-central1-a start \
    --group example-group \
    --template example-template

You can change the default settings for rolling out your update by using the following optional flags:

• --max-num-concurrent-instances, which defines how many instances are updated at the same time.
• --instance-startup-timeout, which defines the maximum amount of time that the updater waits for an instance to start after the updates for that instance are complete. If the instance does not start before the time limit, the updater records the update as a failure.
• --min-instance-update-time, which defines the minimum amount of time that the updater spends to update each instance. The updater starts the next update only when the current update is complete and the minimum update time is spent.
• --max-num-failed-instances, which defines the maximum number of instance updates that can fail before the updater records the entire group update as a failure.

If you do not want to apply an update to all existing instances, you can use the --auto-pause-after-instances flag and the update will automatically pause after updating the number of instances you specified. Afterwards, you can decide whether to cancel or continue the update.

Getting and listing rolling updates

You can list all rolling updates for a managed instance group, including rolling updates that have finished, using the updates list command. The command will list rolling updates up to 30 days ago, but won't contain updates older than 30 days.

To get a list of your rolling updates:

$ gcloud preview rolling-updates --zone us-central1-a list --group example-group

To get information about a single update:

$ gcloud preview rolling-updates --zone us-central1-a describe UPDATE

The value of UPDATE must be the id of the update, returned by the initial start sub-command. You can also get the identifier by performing a rolling-updates describe or rolling-updates list request.

For example, an update id looks like the following:

$ gcloud preview rolling-updates --zone us-central1-a list --group example-group
ID                                    GROUP_NAME    TEMPLATE_NAME   STATUS           STATUS_MESSAGE
a9c939b4-fcd7-a5ec-bde9-e0f92277f718  example-group template-update ROLLING_FORWARD  0/5 instances

Pausing a rolling update

You can pause a rolling update by using the rolling-updates pause sub-command:

$ gcloud preview rolling-updates --zone us-central1-a pause UPDATE

The value of UPDATE must be the id of the update, returned by the initial start sub-command. You can also get the identifier by performing a rolling-updates describe or rolling-updates list request.

If the manager is in the middle of updating an instance, it will finish performing that update before pausing the update. After pausing a rolling update, you can cancel the update, roll it back, or restart it.

Rolling back an update

If your update is misbehaving or you would just like to roll it back, you can roll back an update that is paused by using the rolling-updates rollback sub-command. This stops the update from being applied to more instances, and instances already created with the new template will be recreated with the last template applied before the current update.

To roll back an update:

$ gcloud preview rolling-updates --zone us-central1-a rollback UPDATE

The value of UPDATE must be the id of the update, returned by the initial start sub-command. You can also get the identifier by performing a rolling-updates describe or rolling-updates list request.

Continuing a rolling update

If you paused a rolling update, you can continue the update using the rolling-updates resume sub-command:

$ gcloud preview rolling-updates --zone us-central1-a resume UPDATE

The value of UPDATE must be the id of the update, returned by the initial start sub-command. You can also get the identifier by performing a rolling-updates describe or rolling-updates list request.

Canceling a rolling update

You can cancel a rolling update altogether using the rolling-updates cancel sub-command. This permanently stops the update and the service does not apply the template to additional instances. Instances that have already been recreated in the new template will remain in that state. You can only cancel an update that has already been paused.

For example, to cancel an update in the us-central1-a zone:

$ gcloud preview rolling-updates --zone us-central1-a cancel UPDATE

The value of UPDATE must be the id of the update, returned by the initial start sub-command. You can also get the identifier by performing a rolling-updates describe or rolling-updates list request.

Rolling updates and Autoscaler

A rolling update can be applied to all Managed Instance Groups, whether or not they have autoscaling enabled. If the group is using autoscaling when you start a rolling update, the interaction between the Autoscaler and a rolling update is as follows:

• If you are not using the auto-pause feature for your rolling update, the Autoscaler immediately starts to use the new template for all instances it adds.
• If you are using the auto-pause feature, the Autoscaler continues using the previous template until the update gets automatically paused after updating the subset of instances. After you choose to update the rest of the instances, Autoscaler will start using the new template for any instances it adds. Instances that may have been added by Autoscaler using the old template will get updated to the new template.

Resizing a managed instance group

You can resize a managed instance group with gcloud preview using the managed-instance-groups resize command. Resizing up adds instances to the group using the current instance template; resizing down deletes instances in the following order:

• Instances that are already in the process of deletion.
• Instances that have been targeted for recreation, but have not yet finished deletion.
• Instances that are being created, but have not yet finished creation. This means that either the instance does not exist or it exists but has not yet been added to the specified target pools.
• All other instances, in random order.

The command usage is:

$ gcloud preview managed-instance-groups --zone ZONE resize GROUP \
    --new-size NEW_SIZE

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

--new-size NEW_SIZE

[Required] The desired number of instances in this managed instance group.

Because new instances are created with the latest instance template, it's possible for your managed instance group to contain non-identical instances.

Modifying specific instances

The Instance Group Manager service provides methods for modifying individual instances within the group. Allowed actions are:

• Delete: The instances are deleted, which also removes them from the group.
• Abandon: This removes instances from the group and from any target pools that were specified at creation, without deleting the instances themselves.
• Recreate: Instances are deleted, then recreated using the latest template.

Deleting or abandoning instances reduces the targetSize of the managed instance group. Once the service has deleted or abandoned the specified instances, the currentSize of the group is automatically reduced by the number of instances removed.

Finding instance names

The methods in this section require specific instance names. To find the names of all instances in your managed instance group, you must query the instance group that was automatically created by the instance group manager. To do so:

$ gcloud preview instance-groups --zone ZONE get GROUP

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

Deleting instances

To delete an instance with gcloud preview, use the managed-instance-groups delete-instances sub-command:

$ gcloud preview managed-instance-groups --zone ZONE delete-instances GROUP \
    --instance INSTANCE [INSTANCE ...]

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

--instance INSTANCE [INSTANCE ...]

[Required] The name(s) of one or more instances to be deleted. Separate instance names with a space. For example:

--instance example-id50 example-a2ty example-pcal

Deleting instances reduces the targetSize of the managed instance group and removes the instances from any target pools of which they are a member.

Abandoning instances

To remove an instance from the managed instance group without deleting the instance, use the abandon-instances sub-command. This will also remove the instance from any target pool that was assigned through the Instance Group Manager service; the instance will retain its membership in any target pools that were added outside of this service.

$ gcloud preview managed-instance-groups --zone ZONE abandon-instances GROUP \
    --instance INSTANCE [INSTANCE ...]

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

--instance INSTANCE [INSTANCE ...]

[Required] The name(s) of one or more instances to be abandoned. Separate instance names with a space. For example:

--instance example-id50 example-a2ty example-pcal

Abandoning instances reduces the targetSize of the managed instance group.

Recreating instances

To recreate any instance using the latest template, use the managed-instance-groups recreate-instances sub-command. This command deletes the specified instances, and creates new instances using the current instance template.

$ gcloud preview managed-instance-groups --zone ZONE recreate-instances GROUP \
    --instance INSTANCE [INSTANCE ...]

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

--instance INSTANCE [INSTANCE ...]

[Required] The name(s) of one or more instances to be recreated. Separate instance names with a space. For example:

--instance example-id50 example-a2ty example-pcal

Deleting an instance group manager

You may delete an instance group manager and all of its children with the managed-instance-groups delete sub-command. All instances and instance groups that belong to the instance group manager are deleted:

$ gcloud preview managed-instance-groups --zone ZONE delete GROUP

Where:

--zone ZONE

[Required] The name of the Google Compute Engine zone in which to create this managed instance group.

GROUP

[Required] The name of the managed instance group.

If you'd like to retain any of the instances in the group, use the abandon-instances command first to remove the instances from the group, then delete.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.