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

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, as a best practice.

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 Platform Console, the gcloud compute tool, or the API.

Console

  1. In the GCP Console, go to the Instance Groups page.

    Go to the Instance Groups page

  2. Click Create an instance group.
  3. Enter a name for the managed instance group, and select the zone where you want to locate the group.
  4. Under Group type, select Managed instance group.
  5. Under Instance template, select an instance template. If no templates are available, create an instance template.
  6. 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.
  7. 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 [NAME] \
    --base-instance-name [BASE_NAME] \
    --size [SIZE] \
    --template [INSTANCE_TEMPLATE] \
    --zone [ZONE]

where you would replace the following:

  • [NAME] with the name for this instance group.
  • [BASE_NAME] with the name to use for instances created in this instance group. Since 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, example-qtyz and so on. If you need specific names, see Creating instances with specific names in MIGs
  • [SIZE] with the size of the instance group.
  • [INSTANCE_TEMPLATE] with the name of the instance template to use for this group.

  • [ZONE] is one of the zones available for Compute Engine.

    For example, the following command would create 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://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers

{
  "baseInstanceName": "[BASE_NAME]",
  "versions": [
    {
      "instanceTemplate": "global/instanceTemplates/[INSTANCE_TEMPLATE]"
    }
  ],
  "name": "[NAME]",
  "targetSize": [SIZE]
}

where you would replace the following:

  • [PROJECT_ID] with the project ID for the request.
  • [ZONE] with the zone for the request.
  • [NAME] with the name for this instance group.
  • [BASE_NAME] with the name to use for instances created in this instance group. Since 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, example-qtyz and so on.
  • [SIZE] with the size of the instance group.
  • [INSTANCE_TEMPLATE] with 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 allows you to 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.

Console

  1. Go to the Instance Groups page in the GCP Console.

    Go to the Instance Groups page

  2. Under the Name column of the list, click the name of the instance group where you want to change the instance template.
  3. Click Edit group to modify this managed instance group.
  4. Under Instance template select the new instance template that you want to use on this group.
  5. 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] \
    --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://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers[INSTANCE_GROUP]/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.

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 resizing a managed instance group

If a managed instance group is not already set to automatically scale, you can resize a group manually to change the number of instances in the group. 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 Platform Console, the gcloud compute tool, or the API.

Console

  1. Go to the Instance Groups page in the GCP Console.

    Go to the Instance Groups page

  2. Under the Name column of the list, click the name of the instance group where you want to change the group size.
  3. Click Edit group to modify this managed instance group.
  4. 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.
  5. Click Save to apply the new template.

gcloud

The command usage is:

gcloud compute instance-groups managed resize [INSTANCE_GROUP ] \
    --size [NEW_SIZE] \
    --zone [ZONE]

API

Construct a request to the instanceGroupManagers service with the name of the target managed instance group. Specify the new instance size as a parameter.

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP]/resize?size=[NEW_SIZE]

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.

gcloud

Using the gcloud command-line tool, run the resize command with the --no-creation-retries flag:

gcloud beta compute instance-groups managed resize [INSTANCE_GROUP] --size [NEW_SIZE] \
    --nocreation-retries \
    --zone [ZONE]

API

Construct a request to the instanceGroupManagers service with the name of the target managed instance group. Specify the new instance size and the noCreationRetries field in the request body.

POST https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP]/resizeAdvanced

{
 "targetSize": [SIZE]
 "noCreationRetries": true
}

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 have a currentAction of CREATING_WITHOUT_RETRIES.

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.

Console

  1. Go to the Instance Templates page in the GCP Console.

    Go to the Instance Templates page

  2. Click New instance template.
  3. Fill in the properties that you want for your instance template.
  4. Click Show advanced options to expand the Availability policies section.
  5. Set Preemptibility to On.
  6. Click Create to create the template.
  7. 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.

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

Console

  1. In the GCP Console, go to the Instance Groups page.

    Go to the Instance Groups page

  2. Select one or more groups on the list that you want to delete.
  3. 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] \
    --zone [ZONE]

API

Construct a DELETE request to the instanceGroupManagers service, and specify the name of the managed instance group that you want to delete.

DELETE https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[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 field is 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 backwards 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 Updating Managed Instance Groups.

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

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

POST https://www.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:

[PROJECT_ID]@cloudservices.gserviceaccount.com

where

  • [PROJECT_ID] is the numerical ID of the corresponding project.

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. Please also bear in mind that this account is 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:

  • Been granted the serviceAccountUser role on the instance template, if you plan to create instances that can run as a service account.
  • Permission 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 Updating Managed Instance Groups.

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 will also be 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. Since 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

Trang này có hữu ích không? Hãy cho chúng tôi biết đánh giá của bạn:

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

Trang này
Phản hồi về tài liệu
Compute Engine Documentation
Phản hồi về sản phẩm