Creating Groups of Managed Instances

This page describes how to create a group of managed instances, called a managed instance group, within a zone. A managed instance group contains identical instances that you can manage as a single entity. Managed instance groups maintain high availability of your apps by proactively keeping your instances available, which means in RUNNING state. Managed instance groups support autoscaling, load balancing, rolling updates, autohealing, and more.

You can also create regional managed instance groups which contain instances across multiple zones within the same region. To learn about instance groups, read the Instance Groups Overview.

Before you begin

Limitations

  • Each managed instance group can contain up to 1000 VM instances.
  • When updating a managed instance group, no more than 1000 instances can be specified in a single request.

Using managed instance groups for stateless applications

Managed instance groups are intended to support stateless applications that aren't dependent on the specific state of the underlying VM instances to run. This allows for 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 will automatically recreate the instance with a new root persistent disk.

Because of the stateless nature of managed instance groups, you should design or retrofit your application so that it does not depend on specific instance properties that will not 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 Google 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 software applications installed and has access to required data. For more recommendations around creating instance templates, read Deterministic instance templates.

If you decide that you need to keep around the boot disks associated with your managed instance groups, you can disable the disks.autoDelete option to prevent boot persistent disks from being deleted but keep in mind that will prevent the managed instance group from creating new instances and is not recommended.

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. Go to the Instance Groups page in the GCP Console.

    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, you can enable Autoscaling so that the group will automatically add or remove instances based on instance CPU usage or autohealing to perform health checking on instances within the instance group.
  7. Click Create to create the new group.

gcloud

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

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.
  • [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 service. In the request body, include the desired 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.

Retrieving existing groups and group descriptions

Get information about your existing managed instance groups.

Console

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

    Go to the Instance Groups page.

    If you have existing instance groups, the page lists those groups. Note that this page also lists unmanaged instance groups.

  2. Under the Name column of the list, click the name of the instance group that you want to examine. A page opens with the instance group properties and a list of instances that are included in the group.

gcloud

List all managed instance groups within a project:

gcloud compute instance-groups managed list

To get information about a specific group:

gcloud compute instance-groups managed describe [INSTANCE_GROUP] \
    --zone [ZONE]

API

List all managed instance groups within a project. Construct a GET request to the instanceGroupManagers service:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers

Get information about a specific group. Construct a GET request to the instanceGroupManagers service and include the name of a specific managed instance group:

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP]

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

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 will have the CREATING_WITHOUT_RETRIES status.

Setting up health checking and autohealing for managed instance groups

To improve the availability of your application, and to verify that your application is responding, you can configure an autohealing policy for your managed instance group. An autohealing policy relies on an application-based health check to verify that an application is responding as expected. Checking that an application responds is more precise than simply verifying that an instance is in a RUNNING state.

If the autohealer determines that an application is not responding, the managed instance group automatically recreates that instance.

You can use health-check signals to verify that an instance is created and its application is responding. When a managed instance is in the process of being created, its currentAction is CREATING. If an autohealing policy is attached, once the managed instance is created and running, the instance proceeds to a currentAction of VERIFYING and the health checker begins to probe the instance's application. If the application passes this initial health check within the time that it takes for the application to start, then the instance is verified and its currentAction flips to NONE. When you first attach a health check to a managed instance group, it can take 15 minutes before verification completes. See Verifying the status of instances in a managed instance group for more information.

When autohealing recreates an instance, it uses the instance template that was originally used to create that instance (not necessarily the default instance template attached to the managed instance group). Any data written to an instance's disks is lost when the instance and its disks are deleted and recreated, unless you take precautions. To learn more about how the Compute Engine autohealer behaves and how autohealing affects attached disks, read Managed instance groups and autohealing. You can set up to one autohealing policy for a managed instance group.

As an example of how to use a health check on a managed instance group, follow the instructions below to create a health check that checks for a web server response on port 80. Then, you will apply that health check to a managed instance group to ensure that the web servers in that group function properly:

Console

  1. Create a health check for autohealing that is more conservative than a load balancing health check.

    For example, create a health check that looks for a response on port 80 and that can tolerate some failure before it marks instances as UNHEALTHY and causes them to be recreated. In this example, an instance is marked as healthy if it returns successfully once. It is marked as unhealthy if it returns unsuccessfully 3 consecutive times.

    1. Go to the Create a health check page in the GCP Console.

      Go to the Create a health checks page

    2. Give the health check a name, such as example-check.
    3. For Protocol, select HTTP if not already selected.
    4. For Port, enter 80.
    5. For Check interval, enter 5.
    6. For Timeout, enter 5.
    7. Set a Healthy threshold to determine how many consecutive successful health checks must be returned before an unhealthy instance is marked as healthy. Enter 1 for this example.
    8. Set an Unhealthy threshold to determine how many consecutive unsuccessful health checks must returned before a health instance is marked as unhealthy. Enter 3 for this example.
    9. Click Create to create the health check.
  2. Create a firewall rule to allow health check probes to connect to your application.

    Health check probes come from addresses in the ranges 130.211.0.0/22 and 35.191.0.0/16, so make sure your network firewall rules allow the health check to connect. For this example, our managed instance group uses the default network and its instances are listening on port 80. If port 80 is not already open on the default network, create a firewall rule.

    1. Go to the Create a firewall rule page in the GCP Console.

      Go to the Create a firewall rules page

    2. For Name, enter a name for the firewall rule (for example, allow-health-check).
    3. For Network, select the default network.
    4. For Source filter, select IP ranges.
    5. For Source IP ranges, enter 130.211.0.0/22 and 35.191.0.0/16.
    6. In Protocols and ports, select Specified protocols and ports and enter tcp:80.
    7. Click Create.
  3. Apply the health check by configuring an autohealing policy for your regional or zonal managed instance group.

    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 apply the health check.
    3. Click Edit group to modify this managed instance group.
    4. Under Autohealing, select the health check that you created previously.
    5. Change or keep the Initial delay setting. This setting delays autohealing from potentially prematurely recreating the instance if the instance is in the process of starting up. The initial delay timer starts when the currentAction of the instance is VERIFYING.
    6. Click Save to apply your changes.

    It can take several minutes before autohealing begins monitoring instances in the group.

gcloud

  1. Create a health check for autohealing that is more conservative than a load balancing health check.

    For example, create a health check that looks for a response on port 80 and that can tolerate some failure before it marks instances as UNHEALTHY and causes them to be recreated. In this example, an instance is marked as healthy if it returns successfully once. It is marked as unhealthy if it returns unsuccessfully 3 consecutive times.

    gcloud compute health-checks create http example-check --port 80 \
        --check-interval 30s \
        --healthy-threshold 1 \
        --timeout 10s \
        --unhealthy-threshold 3
    
  2. Create a firewall rule to allow health check probes to connect to your application.

    Health check probes come from addresses in the ranges 130.211.0.0/22 and 35.191.0.0/16, so make sure your firewall rules allow the health check to connect. For this example, our managed instance group uses the default network and its instances are listening on port 80. If port 80 is not already open on the default network, create a firewall rule.

    gcloud compute firewall-rules create allow-health-check \
        --allow tcp:80 \
        --source-ranges 130.211.0.0/22,35.191.0.0/16 \
        --network default
    
  3. Apply the health check by configuring an autohealing policy for your regional or zonal managed instance group.

    Use the set-autohealing command in gcloud beta compute to apply the health check to the managed instance group.

    The initial-delay setting delays autohealing from potentially prematurely recreating the instance if the instance is in the process of starting up. The initial delay timer starts when the currentAction of the instance is VERIFYING.

    For example:

    gcloud beta compute instance-groups managed set-autohealing my-mig \
        --health-check example-check \
        --initial-delay 300 \
        --zone us-east1-b
    

    It can take 15 minutes before autohealing begins monitoring instances in the group.

API

  1. Create a health check for autohealing that is more conservative than a load balancing health check.

    For example, create a health check that looks for a response on port 80 and that can tolerate some failure before it marks instances as UNHEALTHY and causes them to be recreated. In this example, an instance is marked as healthy if it returns successfully once. It is marked as unhealthy if it returns unsuccessfully 3 consecutive times.

    POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/healthChecks
    
    {
     "name": "example-check",
     "type": "http",
     "port": 80,
     "checkIntervalSec": 30,
     "healthyThreshold": 1,
     "timeoutSec": 10,
     "unhealthyThreshold": 3
    }
    
  2. Create a firewall rule to allow health check probes to connect to your application.

    Health check probes come from addresses in the ranges 130.211.0.0/22 and 35.191.0.0/16, so make sure your firewall rules allow the health check to connect. For this example, our managed instance group uses the default network and its instances are listening on port 80. If port 80 is not already open on the default network, create a firewall rule.

    POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/firewalls
    
    {
     "name": "allow-health-check",
     "network": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/networks/default",
     "sourceRanges": [
      "130.211.0.0/22",
      "35.191.0.0/16"
     ],
     "allowed": [
      {
       "ports": [
        "80"
       ],
       "IPProtocol": "tcp"
      }
     ]
    }
    
  3. Apply the health check by configuring an autohealing policy for your regional or zonal managed instance group.

    An autohealing policy is part of an instanceGroupManager resource or regionInstanceGroupManager resource.

    You can set an autohealing policy using the insert or patch methods.

    The following example sets an autohealing policy using the instanceGroupManagers.patch method.

    PATCH https://www.googleapis.com/compute/beta/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP]
    {
      "autoHealingPolicies": [
        {
          "healthCheck": "global/healthChecks/example-check",
          "initialDelaySec": 300
        }
      ],
    }
    

    The initialDelaySec setting delays autohealing from potentially prematurely recreating the instance if the instance is in the process of starting up. The initial delay timer starts when the currentAction of the instance is VERIFYING.

    It can take several minutes before autohealing begins monitoring instances in the group.

    To turn off application-based autohealing, set the autohealing policy to an empty value, autoHealingPolicies[]. The managed instance group will only recreate instances that are not in a RUNNING state.

    You can get the autohealing policy of a managed instance group by reading the instanceGroupManagers.autoHealingPolicies field. You can get a managed instance group resource using one of the following methods:

Viewing historical autohealing operations

You can use the gcloud tool or the API to view past autohealing events.

gcloud

Use the gcloud compute operations list command with a filter to see only the autohealing repair events in your project.

gcloud compute operations list --filter='operationType~compute.instances.repair.*'

To see more information about a specific repair operation, use the describe command. For example:

gcloud compute operations describe repair-1539070348818-577c6bd6cf650-9752b3f3-1d6945e5 --zone us-east1-b

API

For zonal managed instance groups, submit a GET request to the zone's operations resource and include a filter to scope the output list to compute.instances.repair.* events.

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/operations?filter=operationType+%3D+%22compute.instances.repair.*%22

For regional managed instance groups, use the region's operations resource instead of a zone's.

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/region/[REGION]/operations?filter=operationType+%3D+%22compute.instances.repair.*%22

To see more information about a specific repair operation, submit a GET request for that specific operation.

GET https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-east1-b/operations/repair-1539070348818-577c6bd6cf650-9752b3f3-1d6945e5

Identifying instances that are part of a group

To see a list of all instances in a group, see Retrieving existing groups and group descriptions.

To check if a specific instance is currently a member of a group, you can use the console or API.

Console

  1. Go to the VM instances page.

    Go to the VM instances page

  2. Click on an instance in order to access its VM instance details.
  3. If the VM instance is a member of a managed instance group, the name of that managed instance group will appear under the heading In use by. If the VM instance is not a member of a group, the heading In use by will not appear on the instance details page.

API

See Viewing Referrers to VM Instances.

Alternatively, to identify whether an instance is or was a member of a managed instance group, look for these two metadata keys in the instance's metadata:

  • instance-template indicates the template the instance was created from.
  • created-by indicates the managed instance group that created the instance.

Even if you abandon the instance, the instance will still have these metadata entries, unless you manually remove them.

For example, if there was an instance named random-instance-biy and you wanted to know whether the instance was created by a managed instance group, you can describe the instance and look for the above metadata keys. For example:

gcloud compute instances describe random-instance-biy --zone us-central1-f
canIpForward: false
cpuPlatform: Intel Ivy Bridge
creationTimestamp: '2016-08-24T14:11:38.012-07:00'
disks:
- autoDelete: true
  boot: true
  deviceName: persistent-disk-0
  index: 0
  interface: SCSI
  kind: compute#attachedDisk
...[snip]...
metadata:
  items:
  - key: instance-template
    value: projects/123456789012/global/instanceTemplates/example-it
  - key: created-by
    value: projects/123456789012/zones/us-central1-f/instanceGroupManagers/igm-metadata

Deleting individual 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, stop the autoscaler before attempting to delete the instances.

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.

Delete instances from 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 delete individual instances. A page opens with the instance group properties and a list of instances that are included in the group.
  3. On the list of instances, select one or more instances that you want to delete.
  4. Click Delete. The selected instances are deleted.

gcloud

To delete an instance with gcloud, use the instance-groups managed delete-instances subcommand:

gcloud compute instance-groups managed delete-instances [INSTANCE_GROUP] \
    --instances example-i3n2,example-z2x9 \
    --zone [ZONE]

API

Construct a request to the instanceGroupManagers service with the name of the target managed instance group. 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]/deleteInstances

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

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.

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.

Abandon instances from 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 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.
  3. On the list of instances, select one or more instances that you want to remove from the group.
  4. 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] \
    --instances example-i3n2,example-z2x9 \
    --zone [ZONE]

API

Construct a request to the instanceGroupManagers service with the name of the target managed instance group. 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]/abandonInstances

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

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.

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.

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

gcloud

Use the instance-groups managed recreate-instances subcommand.

gcloud compute instance-groups managed recreate-instances [INSTANCE_GROUP] \
    --instances example-i3n2,example-z2x9 \
    --zone [ZONE]

API

Construct a request to the instanceGroupManagers service with the name of the target managed instance group. 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]/recreateInstances

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

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.

Verifying the status of instances in a managed instance group

Several commands and requests create, delete, and modify instances in a managed instance group. Those operations are returned as DONE once the group has scheduled actions to create, delete, or update those instances. However, this does not mean that instances in the group have been created, deleted, or updated until those underlying actions are complete. You must verify the status of those instances with the gcloud compute tool or the API.

gcloud

Use the instance-groups managed list-instances command to list the instances in the group and the current actions for those instances.

gcloud compute instance-groups managed list-instances [INSTANCE_GROUP] \
    --zone [ZONE]

For example:

gcloud compute instance-groups managed list-instances example-group \
    --zone [ZONE]

NAME               STATUS  ACTION   LAST_ERROR
example-group-0gnk RUNNING NONE
example-group-15xy         CREATING Error QUOTA_EXCEEDED: Instance 'example-group-15xy' creation failed: Quota 'IN_USE_ADDRESSES' exceeded.  Limit: 23.0
example-group-18ep         CREATING Error QUOTA_EXCEEDED: Instance 'example-group-18ep' creation failed: Quota 'CPUS' exceeded.  Limit: 24.0, Error QUOTA_EXCEEDED: Instance 'example-group-18ep' creation failed: Quota 'IN_USE_ADDRESSES' exceeded.  Limit: 23.0
example-group-1u1y         CREATING

In this example, example-group contains four instances: one instance that is running, two instances that were attempting to be created but cannot be created due to address and CPU quotas, and one instance that is being created and has not encountered any errors.

For groups of preemptible instances, if preemptible capacity is unavailable, creation actions will fail with the error: ZONE_RESOURCE_POOL_EXHAUSTED. To view past preemption events, see Detecting if an instance was preempted.

Wait until stable

You can use the instance-groups managed wait-until-stable command to automatically check an instance group and make your script wait until all of the instances in the group are stable.

gcloud compute instance-groups managed wait-until-stable example-group \
    --zone [ZONE]

API

Construct a request to the instanceGroupManagers service and specify the name of the managed instance group that contains the instances you want to verify.

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

For example:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-central1-f/instanceGroupManagers/example-group/listManagedInstances

The request gets the following response:

{
 "managedInstances": [
  {
   "instance": "https://content.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-central1-f/instances/example-group-0gnk",
   "id": "16960422116594945029",
   "instanceStatus": "RUNNING",
   "currentAction": "NONE"
  },
  {
   "instance": "https://content.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-central1-f/instances/example-group-15xy",
   "currentAction": "CREATING",
   "lastAttempt": {
    "errors": {
     "errors": [
      {
       "code": "QUOTA_EXCEEDED",
       "message": "Instance 'example-group-15xy' creation failed: Quota 'IN_USE_ADDRESSES' exceeded.  Limit: 23.0"
      }
     ]
    }
   }
  },
  {
   "instance": "https://content.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-central1-f/instances/example-group-18ep",
   "currentAction": "CREATING",
   "lastAttempt": {
    "errors": {
     "errors": [
      {
       "code": "QUOTA_EXCEEDED",
       "message": "Instance 'example-group-18ep' creation failed: Quota 'CPUS' exceeded.  Limit: 24.0"
      },
      {
       "code": "QUOTA_EXCEEDED",
       "message": "Instance 'example-group-18ep' creation failed: Quota 'IN_USE_ADDRESSES' exceeded.  Limit: 23.0"
      }
     ]
    }
   }
  },
  {
   "instance": "https://content.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/us-central1-f/instances/example-group-1u1y",
   "id": "7239700230861444556",
   "instanceStatus": "RUNNING",
   "currentAction": "CREATING"
  }
 ]
}

In this example, example-group contains four instances: one instance that is running, two instances that were attempting to be created but cannot be created due to address and CPU quotas, and one instance that is being created and has not encountered any errors.

For groups of preemptible instances, if preemptible capacity is unavailable, creation actions will fail with the error: ZONE_RESOURCE_POOL_EXHAUSTED. To view past preemption events, see Detecting if an instance was preempted.

Deleting a managed instance group

When you delete a managed instance group using the Google Cloud Platform Console or gcloud, all instances in the group and any attached autoscalers are also 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.

If you delete a managed instance group using the API, Compute Engine does not delete any attached autoscalers, and you would need to do that as a separate request.

Delete an entire managed instance group and its instances 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. 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]

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.

Adding a managed instance group to a load balancer

Google Cloud Platform load balancing uses instance groups, both managed and unmanaged, to serve traffic. Depending on the type of load balancer you are doing, you can add instance groups to a target pool or backend service. To read more about managed instance groups and load balancing, read the Instance Groups Overview.

Adding a managed instance group to a backend service

A backend service is necessary for creating an HTTP(S), internal, or SSL load balancer. A backend service contains individual backends that each contain one instance group, either managed or unmanaged. The instances in the instance group respond to traffic from the load balancer. The backend service in turn knows which instances it can use, how much traffic they can handle, and how much traffic they are currently handling. In addition, the backend service monitors health checking and does not send new connections to unhealthy instances.

For instructions to add an instance group to a backend service, read Adding instance groups to a backend service.

Adding a managed instance group to a target pool

A target pool is an object that contains one or more virtual machine instances. A target pool is used in Network load balancing, where a Network load balancer forwards user requests to the attached target pool. The instances that are part of that target pool serve these requests and return a response. You can add a managed instance group to a target pool so that when instances are added or removed from the instance group, the target pool is also automatically updated with the changes.

Before you can add a managed instance group to a target pool, the target pool must exist. For more information, see the documentation for Adding a target pool.

To add an existing managed instance group to a target pool, follow these instructions. This causes all VM instances that are part of the managed instance group to be added to the target pool.

Console

  1. Go to the Target Pools page in the GCP Console.

    Go to the Target Pools page

  2. Click the target pool you want to add the instance group to.
  3. Click the Edit button.
  4. Scroll down to the VM instances section and click on Select instance groups.
  5. Select an instance group from the drop-down menu.
  6. Save your changes.

gcloud

With the gcloud command-line tool, use the set-target-pools command:

gcloud compute instance-groups managed set-target-pools [INSTANCE_GROUP] \
    --target-pools [TARGET_POOL,..] [--zone ZONE]

where:

  • [INSTANCE_GROUP] is the name of the instance group.
  • [TARGET_POOL] is the name of one or more target pools to add this instance group to.
  • [ZONE] is the zone of the instance group.

API

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

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

where:

  • [PROJECT_ID] is the project ID for this request.
  • [ZONE] is the zone for the instance group.
  • [INSTANCE_GROUP] is the name of the instance group.

The request body should contain a list of URIs to the target pools you want to add this group. For example:

{
  "targetPools": [
    "regions/us-central1/targetPools/example-targetpool-1",
    "regions/us-central1/targetPools/example-targetpool-2"
  ]
}

Assigning named ports to managed instance groups

Named ports are key:value pairs that represent a service name and the port number that the service runs on. Named ports are used by load balancing services to direct traffic to specific ports on individual instances. For example, if you set a named port as http:80 and then configure your backend service to send traffic to a port named http, the load balancing will forward traffic to port 80 of individual instances that are part of the instance group.

Named ports are simple metadata used by load balancing. Named ports do not control network or firewall resources in Compute Engine.

You can assign multiple ports for each service name and multiple service names for each port. However, keep in mind that a given backend service can only forward traffic to one named port at a time.

Console

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

    Go to the Instance Groups page

  2. Click the name of the instance group where you want to specify named ports. A page opens with the instance group properties.
  3. Click Edit group to modify this managed instance group.
  4. Click Specify port name mapping to expand the named ports options.
  5. Click Add item, and enter the desired port name and the port numbers that you want to associate with that name. Click Add item again to add additional entries if necessary.
  6. Click Save to save your changes and apply the named ports to the instances in the managed instance group.

gcloud

Set one or more named ports using the set-named-ports command:

gcloud compute instance-groups managed set-named-ports [INSTANCE_GROUP] \
  --named-ports [PORT_NAME]:[PORT],[PORT_NAME]:[PORT]

For example:

gcloud compute instance-groups managed set-named-ports [INSTANCE_GROUP] \
  --named-ports name1:80,name2:8080

To assign multiple ports to each service name or multiple names for each service, create more than one entry for each name or port. For example, assign name1 to ports 10, 20, and 80. Then, assign both name2 and name3 to port 80. Finally, assign port 9000 to name4.

gcloud compute instance-groups managed set-named-ports [INSTANCE_GROUP] \
  --named-ports name1:10,name1:20,name1:80,\
                name2:8080,name3:8080,\
                name4:9000

Check the named ports assignments for an managed instance group using the get-named-ports command:

gcloud compute instance-groups managed get-named-ports [INSTANCE_GROUP]

NAME  PORT
name1 10
name1 20
name1 80
name2 8080
name3 8080
name4 9000

API

The Instance Group Manager API does not offer a setNamedPorts API method but you can use Instance Group API to perform this task instead.

Construct a request to the Instance Group API and include the name of the instance group. Obtain the current fingerprint value for the instance group by getting information about a specific group. Include the fingerprint and one or more namedPorts value pairs in the request body:

POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroups/[INSTANCE_GROUP]/setNamedPorts

{
 "fingerprint": "42WmSpB8rSM=",
 "namedPorts": [
  {
   "name": "[PORT_NAME]",
   "port": [PORT_NUMBER]
  },
  {
   "name": "[PORT_NAME]",
   "port": [PORT_NUMBER]
  }
 ]
}

For example:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-group/setNamedPorts

{
 "fingerprint": "42WmSpB8rSM=",
 "namedPorts": [
  {
   "name": "name1",
   "port": 80
  },
  {
   "name": "name2",
   "port": 8080
  }
 ]
}

To assign multiple ports to each service name, create multiple entries for that service name. For example, you can assign ports 10, 20, and 80 to name1. Also assign port 8080 to name2.

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-group/setNamedPorts

{
 "fingerprint": "42WmSpB8rSM=",
 "namedPorts": [
  {
   "name": "name1",
   "port": 10
  },
  {
   "name": "name1",
   "port": 20
  }
  {
   "name": "name1",
   "port": 80
  }
  {
   "name": "name2",
   "port": 8080
  }
  {
   "name": "name3",
   "port": 80
  }
  {
   "name": "name4",
   "port": 8080
  }
 ]
}

To list the named ports that are already assigned to a managed instance group, construct a GET request that points to the group:

GET 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

Was this page helpful? Let us know how we did:

Send feedback about...

Compute Engine Documentation