Creating managed instance groups

A managed instance group (MIG) contains identical instances that are based on an instance template. MIGs maintain high availability of your applications by proactively keeping your instances available, that is, in the RUNNING state.

Managed instance groups support autohealing, load balancing, autoscaling, and auto-updating.

You can create both zonal (single-zone) MIGs and regional (multi-zone) MIGs. Regional MIGs provide higher availability with instances spread across multiple zones within the same region.

To learn more about instance groups, read the Instance groups overview.

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.

Limitations

Each managed instance group can contain up to 1,000 virtual machine (VM) instances.
When updating a managed instance group, no more than 1,000 instances can be specified in a single request.

Using managed instance groups for stateless apps

Managed instance groups support stateless apps that don't depend on the specific state of the underlying VM instances to run. This enables features like autoscaling and autohealing, where the managed instance group can delete and recreate instances automatically. In addition, if an instance is deleted from a managed instance group because of a user action, as part of autohealing, or because of infrastructure maintenance when the instance is not set to live migrate, the instance group automatically recreates the instance with a new root persistent disk.

Because of the stateless nature of managed instance groups, you should design or retrofit your app so that it does not depend on specific instance properties that don't persist, such as an IP address or in-memory data. Likewise, the default behavior for boot persistent disks is to delete them when the corresponding VM instance is deleted, so you should not rely on boot disks as persistent data in a managed instance group.

To retain your data, Google recommends that you regularly maintain up-to-date OS images, use startup scripts, and back up your data in another centralized location, such as Cloud Storage.

In your instance templates, you can specify a container image or a custom image and relevant startup scripts, so that when an instance is recreated, it has the necessary apps installed and has access to required data. For more recommendations around creating instance templates, read Deterministic instance templates.

To save the disks associated with your managed instance groups, disable the disks.autoDelete option to prevent persistent disks from being deleted. If the instance that uses the disk is deleted (for example, if the autoscaler scales down the group or if you manually delete the instance), then you need to manually clean up the remaining disks, if desired.

Creating a managed instance group

Before you create a managed instance group, you must create an instance template to specify the operating system image or container image and the settings for every instance in the group.

After you create the template, create the managed instance group through the Google Cloud Console, the gcloud compute tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

All permissions required to call the instanceGroupManagers.insert method

Console

In the Cloud Console, go to the Instance Groups page.
Go to the Instance Groups page
Click Create an instance group.
Enter a name for the managed instance group, and select the zone where you want to locate the group.
Under Group type, select Managed instance group.
Under Instance template, select an instance template. If no templates are available, create an instance template.
Specify the number of instances that you want to create in the group. Optionally, enable Autoscaling so that the group will automatically add or remove instances based on its utilization, or enable autohealing to perform application-based health checking on instances within the group.
Click Create to create the new group.

gcloud

Create an instance group with the instance-groups managed create subcommand:

gcloud compute instance-groups managed create instance-group-name \
    --base-instance-name base-name \
    --size size \
    --template instance-template \
    --zone zone

Replace the following:

instance-group-name: The name for this instance group.
base-name: The name to use for instances created in this instance group. Because these instances are identical, instances are assigned a random string as part of their instance name. The base name is prepended to this random string. For example, if the base name was example, instances would have names like example-yahs and example-qtyz. If you need specific names, see Creating instances with specific names in MIGs
size: The size of the instance group.
instance-template: The name of the instance template to use for this group.
zone: One of the zones available for Compute Engine.

For example, the following command creates an instance group named example-group, whose base instance name is test. The group contains three instances:
```
gcloud compute instance-groups managed create example-group \
  --base-instance-name test \
  --size 3 \
  --template an-instance-template
```

API

In the API, construct a POST request to the instanceGroupManagers.insert method or the regionInstanceGroupManagers.insert method. In the request body, include the group name, group size, base name for instances in the group, and the URL to the instance template.

POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers

{
  "baseInstanceName": "base-name",
  "versions": [
    {
      "instanceTemplate": "global/instanceTemplates/instance-template"
    }
  ],
  "name": "instance-group-name",
  "targetSize": size
}

Replace the following:

project-id: The project ID for the request.
zone: The zone for the request.
instance-group-name: The name for this instance group.
base-name: The name to use for instances created in this instance group. Because these instances are identical, instances are assigned a random string as part of their instance name. The base name is prepended to this random string. For example, if the base name was example, instances would have names like example-yahs and example-qtyz.
size: The size of the instance group.
instance-template: The instance template to use for this group.

Depending on how you configure and act on a MIG, various policies and actions can affect the instances in the group. To determine which managed instances are up and running, see Checking the status of managed instances.

Changing the instance template for a managed instance group

You can change the instance template for a managed instance group without applying any changes to existing instances. The managed instance group uses the new template when you make a request to add or recreate instances, but the template does not automatically update existing instances in the group. This lets you control exactly which instances are updated, but it causes your instance group to contain dissimilar instances.

After you create a new instance template, change the instance template for an existing instance group.

Permissions required for this task

To perform this task, you must have the following permissions.

All permissions required to call the instanceGroupManagers.setInstanceTemplate method

Console

In the Cloud Console, go to the Instance groups page.
Go to the Instance groups page
Under the Name column of the list, click the name of the instance group where you want to change the instance template.
Click Edit group to modify this managed instance group.
Under Instance template, select the new instance template that you want to use on this group.
Click Save to apply the new template.

gcloud

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

gcloud compute instance-groups managed set-instance-template instance-group-name \
    --template instance-template \
    --zone zone

API

Construct a request to the instanceGroupManagers service with the name of the target managed instance group. Include the URL of the new instance template in the request body:

POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/setInstanceTemplate

{
 "instanceTemplate": "global/instanceTemplates/instance-template
}

After you change the instance template, recreate individual instances or update all of the instances in the group with a rolling update.

Resizing a managed instance group

To add or remove instances in a MIG, you can:

Use autoscaling for stateless applications.
Manually set the size of the MIG.
Create instances with specific names or delete or abandon specific instances.

Automatically resizing a managed instance group

You can configure managed instance groups to automatically add or remove instances based on their workloads. Your applications can gracefully handle increases in traffic, and you can reduce your costs when the need for compute resources is lower. To start scaling your managed instance groups, see Autoscaling groups of instances.

Manually setting the size of a managed instance group

If a managed instance group is not already set to automatically scale, you can resize the group manually to change the number of instances. If you increase the size, the managed instance group uses the current instance template to add new instances. If you decrease the size, the managed instance group deletes instances from the group. The group deletes instances with a currentAction of DELETING, CREATING, and RECREATING before it deletes instances that are running with no scheduled actions.

If the group is part of a backend service that has enabled connection draining, it can take up to 60 seconds after the connection draining duration has elapsed before the VM instance is removed or deleted.

You can resize a managed instance group using the Google Cloud Console, the gcloud compute tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

compute.instanceGroupManagers.update on the managed instance group

Console

In the Cloud Console, go to the Instance groups page.
Go to the Instance groups page
Under the Name column of the list, click the name of the instance group where you want to change the group size.
Click Edit group to modify this managed instance group.
Under Number of instances, specify the number of instances that you want to include in this managed instance group. If Autoscaling is enabled, the group is automatically adding or removing instances as necessary. However, you can change the Minimum number of instances and the Maximum number of instances values to indirectly adjust the group size through Autoscaler.
Click Save to apply the new template.

gcloud

Use the resize subcommand.

gcloud compute instance-groups managed resize instance-group-name \
    --size new-size \
    --zone zone

API

Construct a request to the resize method. Specify the new instance size as a parameter.

POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/resize?size=new-size

If the instance group is a regional managed instance group, replace zones/zone with regions/region.

After you make a request to resize a managed instance group, the instances start or stop as soon as the system can provision or delete them. This process can take a significant amount of time depending on the number of instances in the group. Verify the status of instances in your managed instance group.

Disabling creation retries mode during resize

By default, if the initial creation of a virtual machine instance fails, the managed instance group continuously retries to create each instance, until the instance is successfully created. However, if you do not want automatic creation retries, you can disable the creation retry mode by providing the --nocreation-retries flag when you resize the instance group. In this mode, the managed instance group attempts to create all instances only once. If there is an error during creation, the managed instance group will not create this instance, and will decrease the target size of the managed instance group instead.

This mode applies only during the first creation attempt of an instance. If an instance is created successfully while this mode is enabled, the instance behaves the same way as all other instances created with a regular resize request. In particular, if a running instance dies unexpectedly at a later time and needs to be recreated, this mode does not affect the recreation behavior in that scenario.

The disable creation retry mode is especially useful in scenarios where you have systems automatically creating groups of instances where an exact number of instances is not required. You might prefer to stabilize quickly on the size of the managed instance group and be flexible in the number of instances in the group, rather than to wait indefinitely until all the requested instances are created, which might be delayed temporarily or permanently because of quota errors or other unrelated issues.

To resize a managed instance group in the disabled creation retries mode, use the gcloud compute tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

compute.instanceGroupManagers.update on the managed instance group

gcloud

Use the resize subcommand with the --no-creation-retries flag:

gcloud beta compute instance-groups managed resize instance-group-name --size new-size \
    --nocreation-retries \
    --zone zone

API

Construct a request to resizeAdvanced method. Specify the new instance size and the noCreationRetries field in the request body.

POST https://compute.googleapis.com/compute/beta/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/resizeAdvanced

{
 "targetSize": size
 "noCreationRetries": true
}

If the instance group is a regional managed instance group, replace zones/zone with regions/region.

You can see which instances are being created and in which mode by using the listManagedInstances method. Instances that are being created in the disabled creation retries mode will have a currentAction of CREATING_WITHOUT_RETRIES.

Creating instances with specific names in MIGs (beta)

If you have a system that depends on specific names, you can create instances with those names. The names that you assign to these managed instances persist if the instance is recreated. See Adding instances with specific names.

Deleting specific instances from a group

You can delete individual instances in a managed instance group. Deleting instances reduces the specified targetSize of the instance group and removes the instances from any target pools of which they are a member.

Deleting instances from a managed instance group does not change any specified autoscaler settings. If you delete instances from a managed instance group, the autoscaler might detect an increase in the workload on the other instances in the group and increase the group size back to its previous level. To prevent this, turn off or delete the autoscaler before attempting to delete the instances.

Delete instances from a managed instance group using the Google Cloud Console, the gcloud compute tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

compute.instanceGroupManagers.update on the managed instance group

Console

In the Cloud Console, go to the Instance groups page.
Go to the Instance groups page
Under the Name column of the list, click the name of the instance group where you want to delete individual instances. A page opens with the instance group properties and a list of instances that are included in the group.
On the list of instances, select one or more instances that you want to delete.
Click Delete. The selected instances are deleted.

gcloud

Use the instance-groups managed delete-instances subcommand:

gcloud compute instance-groups managed delete-instances instance-group-name \
    --instances example-i3n2,example-z2x9 \
    --zone zone

API

Construct a request to the instanceGroupManagers.deleteInstances method. In the request body, include the URLs to one or more instances that you want to delete.

POST https://www.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/deleteInstances

{
 "instances": [
  "zones/zone/instances/example-instance-i3n2",
  "zones/zone/instances/example-instance-l6n1"
 ]
}

If the instance group is a regional managed instance group, replace zones/zone with regions/region.

After you make a request to delete instances in a managed instance group, the instances stop as soon as the system can delete them. This process can take a significant amount of time depending on the number of instances that you delete from the group. Verify the status of instances in your managed instance group.

Abandoning instances from a group

You can separate an instance from a managed instance group to more easily debug issues with individual instances without affecting the group as a whole. Abandoning an instance from a group also removes the instance from load balancers that were assigned to the managed instance group. Target pools that were manually assigned to specific individual instances are not removed.

Abandoning instances reduces the specified targetSize of the instance group, but does not change any specified autoscaler settings. Managed instance groups with an autoscaler continue to add or remove instances automatically as necessary.

Abandon instances from a managed instance group using the Google Cloud Console, the gcloud compute tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

compute.instanceGroupManagers.update on the managed instance group

Console

In the Cloud Console, go to the Instance groups page.
Go to the Instance groups page
Under the Name column of the list, click the name of the instance group from which you want to remove instances. A page opens with the instance group properties and a list of instances that are included in the group.
On the list of instances, select one or more instances that you want to remove from the group.
Click Remove from group. The selected instances leave the group, but continue to run outside of the group.

gcloud

To remove an instance from the instance group without deleting the instance, use the abandon-instances subcommand.

gcloud compute instance-groups managed abandon-instances instance-group-name \
    --instances example-i3n2,example-z2x9 \
    --zone zone

API

Construct a request to the instanceGroupManagers.abandonInstances method. In the request body, include the URLs to one or more instances that you want to abandon.

POST https://www.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/abandonInstances

{
 "instances": [
  "zones/zone/instances/example-instance-i3n2",
  "zones/zone/instances/example-instance-l6n1"
 ]
}

If the instance group is a regional managed instance group, replace zones/zone with regions/region.

After you make a request to abandon instances from a managed instance group, the group removes the instances as soon as possible. Verify the status of instances in your managed instance group.

Recreating instances in the group

Recreating the instance deletes the specified instances and creates new instances using the instance template that is assigned to the managed instance group.

Use this method to update selected instances so that they use the latest instance template. If you need to recreate all of the instances in a managed instance group, start a rolling update instead.

Recreate selected instances in managed instance group using the gcloud compute tool, or the API.

Permissions required for this task

To perform this task, you must have the following permissions.

compute.instanceGroupManagers.update on the managed instance group

gcloud

Use the instance-groups managed recreate-instances subcommand.

gcloud compute instance-groups managed recreate-instances instance-group-name \
    --instances example-i3n2,example-z2x9 \
    --zone zone

API

Construct a request to the instanceGroupManagers.recreateInstances method. In the request body, include the URLs to one or more instances that you want to recreate.

POST https://www.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/recreateInstances

{
 "instances": [
  "zones/zone/instances/example-instance-i3n2",
  "zones/zone/instances/example-instance-l6n1"
 ]
}

If the instance group is a regional managed instance group, replace zones/zone with regions/region.

After you make a request to recreate instances in a managed instance group, the new instances start as soon as the system can provision them. This process can take a significant amount of time depending on the number of instances that you recreate. Verify the status of instances in your managed instance group.

Deleting a managed instance group

When you delete a managed instance group, all instances in the group are deleted. If you must keep any of the instances in this managed instance group, abandon the instances first to remove the instances from the group. Then, delete the managed instance group.

When you delete a managed instance group and its instances using the Google Cloud Console or the gcloud compute tool, any attached autoscalers are automatically deleted. However, if using the API, you must first issue separate requests to delete any attached autoscalers with autoscalers.delete or regionAutoscalers.delete.

Permissions required for this task

To perform this task, you must have the following permissions.

compute.instanceGroupManagers.delete on the managed instance group

Console

In the Cloud Console, go to the Instance groups page.
Go to the Instance groups page
Select one or more groups on the list that you want to delete.
Click Delete to delete the group and all of the instances in the managed instance group.

gcloud

Use the instance-groups managed delete subcommand.

gcloud compute instance-groups managed delete instance-group-name \
    --zone zone

API

Construct a request to the instanceGroupManagers.delete method.

DELETE https://www.googleapis.com/compute/v1/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.

Creating groups of preemptible instances

You can use managed instance groups to quickly create multiple preemptible instances, which can reduce the costs of the instances in your managed instance groups. For example, you can create a group of preemptible instances, use them to run a batch processing task, and then delete the group when the task is complete.

To create a group of preemptible instances, set the premptible option in an instance template, and then use the template to create the managed instance group.

Permissions required for this task

To perform this task, you must have the following permissions.

All permissions required to create a new instance
compute.instanceTemplates.use on the instance template

Console

In the Cloud Console, go to the Instance templates page.
Go to the Instance templates page
Click New instance template.
Fill in the properties that you want for your instance template.
Click Show advanced options to expand the Availability policies section.
Set Preemptibility to On.
Click Create to create the template.
Use this template to create a managed instance group

gcloud

In gcloud compute, create an instance template using the instance-templates create command. Include the --preemptible flag.

gcloud compute instance-templates create instance-template \
    --preemptible

After you create the instance template, use it to create a managed instance group.

API

Use the instanceTemplates().insert method to create a new instance template. Include the preemptible property under scheduling and set it to true.

{
"name": "instance-template",
"properties": {
  "machineType": "zones/zone/machineTypes/machine-type",
  "networkInterfaces": [
    {
      "network": "global/networks/default",
      "accessConfigs":
      [
        {
          "name": "external-IP",
          "type": "ONE_TO_ONE_NAT"
        }
      ]
    }
  ],
  "scheduling":
  {
    "preemptible": true
  },
  "disks":
  [
    {
      "type": "PERSISTENT",
      "boot": true,
      "mode": "READ_WRITE",
      "initializeParams":
      {
        "sourceImage": "projects/debian-cloud/global/images/family/debian-9"
      }
    }
  ]
  }
}

After you create the instance template, use it to create a managed instance group.

Understanding the `instanceTemplate` and `versions` fields

When you create a managed instance group, you supply an instance template that the managed instance group uses to create individual VM instances. By default, Compute Engine describes the instance template used in two separate API properties: the top-level instanceTemplate property and the versions property. For example, in the following managed instance group, notice that both the instanceTemplate and versions fields are populated:

{

 "name": "example-group",
 "zone": "zones/us-central1-a",
 "instanceTemplate": "global/instanceTemplates/example-it",
 "versions": [
  {
   "name": "v3",
   "instanceTemplate": "global/instanceTemplates/example-it",
   "targetSize": {
    "calculated": 3
   }
  }
 ]...
}

Compute Engine automatically populates both the top-level instanceTemplate field and the versions field for backward compatibility. We recommend specifying the versions field and omitting the top-level instanceTemplates field whenever possible. However, if your application code currently sets the top-level instanceTemplate field, it is still a valid request.

To learn more about the Managed Instance Group Updater, read Rolling out updates to MIGs.

(Advanced) Canarying instance templates with a managed instance group

It is possible to create a managed instance group where there are two groups of VMs that use different instance templates. For example, you might want to create a managed instance group that has 20 VM instances and 10 VMs should run on a specific operating image while the rest run on a different operating system image. This feature allows you to compare the two different instance template versions before deciding on one.

Permissions required for this task

To perform this task, you must have the following permissions.

All permissions required to call the instanceGroupManagers.insert method

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

POST https://compute.googleapis.com/compute/beta/projects/project-id/zones/zone/instanceGroupManagers

Your request body should omit the top-level instanceTemplates field but contain the versions property with two instance templates set. In each versions object, you specify an instance template. For one of the versions objects but not both, you must also specify the targetSize. For example, the following request creates an instance group where 50% of the VM instances use the example-template instance template and the rest of the VM instances use the small-machine-type template:

{
  "baseInstanceName": "example-instances",
  "name": "example-group",
  "targetSize": 5,
  "versions":
  [
    {
      "instanceTemplate": "global/instanceTemplates/example-template",
      "targetSize":
      {
        "percent": 50
      }
    },
   {
     "instanceTemplate": "global/instanceTemplates/small-machine-type"
   }
  ]
}

Managed instance groups and IAM

All the operations performed by Compute Engine as part of the managed instance group are performed using the Google APIs service account for your project. This per-project service account has an email address like the following, where project-id is the numerical ID of the corresponding project:

project-id@cloudservices.gserviceaccount.com

The Google APIs service account is different from the default Compute Engine service account.

It is up to you to ensure that the service account used by the managed instance group has enough privileges to create virtual machine instances based on the instance template. In particular, this means that the service account needs to be granted the compute.instanceAdmin.v1 and, optionally, the serviceAccountUser role, to create and manage instances in the instance group. The serviceAccountUser role is required only if the managed instance group will be creating instances that can run as a service account. Keep in mind that this account is also used by other processes, including Deployment Manager.

When you create a managed instance group or update an instance template, Compute Engine validates that the Google APIs service account has the following:

serviceAccountUser role. Important if you plan to create instances that can run as a service account.
Permissions to all the resources referenced from instance templates, such as images, disks, VPC networks and subnets.

To learn more about service accounts, read the Service accounts overview.

Updating all instances in a managed instance group

See Rolling out updates to MIGs.

Troubleshooting

My managed instance group keeps failing to create an instance. What's going on?

There are several issues that can prevent the instance group from successfully creating or recreating an instance. Some common issues include:

The managed instance group is attempting create or recreate both the instance and the boot persistent disk, but the persistent disk already exists. By default, new boot persistent disks are created when new instances are created. These disks are named after the instance. If an instance has the name my-awesome-instance, the disk is also named my-awesome-instance. If a persistent disk already exists with that name, the request fails. Delete the existing persistent disk to resolve this issue.
Your instance template has set the disks.autoDelete option to false for boot persistent disks so that when an instance has been deleted (for example, because of autohealing), the persistent disk was not deleted. When the managed instance group attempted to recreate the instance with the same name, it ran into the same issue where a persistent disk already exists with the same name. Delete the existing persistent disk to resolve the immediate problem and update the instance template to set the disks.autoDelete to true if you would like boot persistent disks to be deleted alongside the instance.
Your instance template might be invalid. If you updated your instance template recently, there could be an invalid property that causes the managed instance group to fail instance creation. Some invalid properties could be:
- You specified a resource that doesn't exist, such as a source image.
- You misspelled a resource name.
- You tried to attach additional non-boot persistent disks in read/write mode. Because instance groups contain multiple instances, any additional disks you want to share between all of the instances in the group can be attached only in read-only mode.

What's next

Create an instance template to use in a managed instance group.
Learn about working with managed instances, for example, learn to delete, abandon, and recreate managed instances, or to create managed instance with specific names.
Get info about managed instance groups and managed instances.
Choose a load balancer or add an instance group to a load balancer.
Enable autohealing for your managed instance group.
Choose a load balancer or add an instance group to a load balancer.
Enable autoscaling for your managed instance group.
Use the auto-updater to update your managed instances with a new template.
Try a tutorial:

Before you begin

Limitations

Using managed instance groups for stateless apps

Creating a managed instance group

Permissions required for this task

Console

gcloud

API

Changing the instance template for a managed instance group

Permissions required for this task

Console

gcloud

API

Resizing a managed instance group

Automatically resizing a managed instance group

Manually setting the size of a managed instance group

Permissions required for this task

Console

gcloud

API

Disabling creation retries mode during resize

Permissions required for this task

gcloud

API

Creating instances with specific names in MIGs (beta)

Deleting specific instances from a group

Permissions required for this task

Console

gcloud

API

Abandoning instances from a group

Permissions required for this task

Console

gcloud

API

Recreating instances in the group

Permissions required for this task

gcloud

API

Deleting a managed instance group

Permissions required for this task

Console

gcloud

API

Creating groups of preemptible instances

Permissions required for this task

Console

gcloud

API

Understanding the instanceTemplate and versions fields

(Advanced) Canarying instance templates with a managed instance group

Permissions required for this task

Managed instance groups and IAM

Updating all instances in a managed instance group

Troubleshooting

What's next

Gửi phản hồi về...

Understanding the `instanceTemplate` and `versions` fields