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 support autoscaling, load balancing, rolling updates, 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 root persistent disks is to delete them when the corresponding VM instance is deleted so you should not rely on root 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 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 root disks associated with your managed instance groups, you can disable the disks.autoDelete option to prevent root 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 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 Cloud Platform 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]",
  "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 Cloud Platform 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 Cloud Platform 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 Cloud Platform 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 permenantly 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 for managed instance groups

To monitor and keep your instances running properly within an instance group, you can apply health checks to the instance group. If a health check determines that a service has failed on an instance, the group automatically recreates that instance. These checks are more precise than simply verifying that a server is in a RUNNING state.

The health checks used by managed instance groups are the same health checks used by load balancing, with some differences in behavior. Health checks that you apply to load balancing services help a load balancer determine where to direct network traffic. These health checks do not cause Compute Engine to recreate instances. Health checks that you apply to managed instance groups will proactively signal to the managed instance group to delete and recreate instances if they become UNHEALTHY.

For the majority of scenarios, use separate health checks for load balancing and for monitoring managed instance groups. Health checking for load balancing can and should be more aggressive since these health checks determine whether an instance receives user traffic. Since customers might rely on your services, you want to catch non-responsive instances quickly so you can redirect traffic if necessary. In contrast, health checking for instance groups will cause Compute Engine proactively replace failing instances so you could create health checks that are more conservative than health checks for a load balancer.

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. Go to the Create a health check page in the Cloud Platform Console.

    Go to the Create a health checks page

  2. Create a new health check that looks for a response on port 80 and can tolerate some failure before it marks instances as UNHEALTHY, causing them to be recreated.

    1. Give the health check a name, such as example-check.
    2. For Protocol, select HTTP if not already selected.
    3. For Port, enter 80.
    4. Expand the More item.
    5. For Check interval, enter 5.
    6. For Timeout, enter 5.
    7. Set a Healthly 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 Unhealthly 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.
  3. Make sure your network firewall rules allow the health check to connect to instances on port 80. For this example, our managed instance group uses the default network. If port 80 is not already open on your default network, create a firewall rule.

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

      Go to the Create a firewall rules page

    2. Enter a name for the firewall rule.
    3. For Network, select the default network.
    4. For Source filter, select Allow from any source (0.0.0.0/0).
    5. In Allowed protocols and ports, enter tcp:80.
    6. Click Create.
  4. Apply to health check to your managed instance group.

    1. Go to the Instance Groups page in the Cloud Platform 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 allows instances to start and finish running their startup scripts so that the managed instance group does not prematurely recreate that instance.
    6. Click Save to apply your changes.

gcloud

  1. Create a health check that looks for a response on port 80 and can tolerate some failure before it marks instances as UNHEALTHY, causing 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. Make sure your firewall rules allow the health check to connect to the instances on port 80. For this example, our managed instance group uses the default network. If port 80 is not already open on your default network, create a firewall rule.

    gcloud compute firewall-rules create allow-http \
        --allow tcp:80 \
        --source-ranges 0.0.0.0/0 \
        --network default
    
  3. Use the set-autohealing command in gcloud beta compute to apply the health check to the managed instance group. The --initial-delay flag allows the instances to start and finish running their startup scripts so that the managed instance group does not prematurely recreate that instance.

    gcloud beta compute instance-groups managed set-autohealing [INSTANCE_GROUP] \
        --health-check example-check \
        --initial-delay 120 \
        --zone [ZONE]
    

API

  1. Create a health check that looks for a response on port 80 and can tolerate some failure before it marks instances as UNHEALTHY and causing them to be recreated.

    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. Make sure your firewall rules allow the health check to connect to the instances on port 80. For this example, our managed instance group uses the default network. If port 80 is not already open on your default network, create a firewall rule.

    POST https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/firewalls
    
    {
     "name": "allow-http",
     "network": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/networks/default",
     "sourceRanges": [
      "0.0.0.0/0"
     ],
     "allowed": [
      {
       "ports": [
        "80"
       ],
       "IPProtocol": "tcp"
      }
     ]
    }
    
  3. In the Compute Engine Beta API, use the instanceGroupManagers.setAutoHealingPolicies method to apply the health check to the managed instance group. The initialDelaySec property allows the instances to start and finish running their startup scripts so that the managed instance group does not prematurely recreate that instance.

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

Identifying instances that are part of a group

To identify whether an instance is or was a part 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.

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

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

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 Cloud Platform 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 Cloud Platform 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 apply update instances so that they use the latest instance group.

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

If you need to recreate all of the instances in a managed instance group, start a rolling update.

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 scheduled 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 but has not yet encountered any errors.

Alternatively, 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"
  }
 ]
}

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

    Go to the Target Pools page

  2. Click on 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 Cloud Platform 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]

Updating all instances in a managed instance group

You can update all of the instances in a managed instance group at once rather than updating the instances individually. Use this process to easily apply a new instance template to all of the existing instances in a managed instance group.

Starting a rolling update

First, create a new instance template with the desired instance properties and disk image. Then, start a rolling update to apply the new template to the instances in the managed instance group. If you set a new template for the group without updating your existing instances, only the instances that you recreate or add to the group later will receive the new template.

Start a rolling update using the gcloud compute tool.

gcloud alpha compute rolling-updates start \
    --group [INSTANCE_GROUP] \
    --template [INSTANCE_TEMPLATE] \
    --zone [ZONE]

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

  • --max-num-concurrent-instances, which defines how many instances are updated at the same time.
  • --instance-startup-timeout, which defines the maximum number of seconds that the update waits for an instance to start after the updates have been applied. If the instance does not start before the time limit, the updater records the update as a failure.
  • --min-instance-update-time, which defines the minimum number of seconds that the updater spends to update each instance. The updater starts the next update only when the current update is complete and the minimum update time is spent.
  • --max-num-failed-instances, which defines the maximum number of instance updates that can fail before the updater records the entire group update as a failure.
  • --auto-pause-after-instances, which tells the update to automatically pause after updating a specific number of instances. After the pause, you can decide whether to cancel or continue the update.

Monitoring rolling updates

View a list of rolling updates with the updates list command. The list includes rolling updates that completed up to 30 days ago.

To view a list your rolling updates:

gcloud alpha compute rolling-updates list \
    --group [INSTANCE_GROUP] \
    --zone [ZONE]

To view information about a single update, use the describe subcommand:

gcloud alpha compute rolling-updates describe UPDATE --zone [ZONE]

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

For example, an update id looks like the following:

gcloud alpha compute rolling-updates list --group example-group
ID                                    GROUP_NAME    TEMPLATE_NAME   STATUS           STATUS_MESSAGE
a9c939b4-fcd7-a5ec-bde9-e0f92277f718  example-group template-update ROLLING_FORWARD  0/5 instances

Pausing a rolling update

You can pause a rolling update with the rolling-updates pause subcommand:

gcloud alpha compute rolling-updates pause [UPDATE_ID] --zone [ZONE]

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

If the group is in the middle of an update for a single instance, it will pause after it finishes that specific instance update. After you pause a rolling update, you can cancel the update, roll it back, or restart it.

Rolling back an update

You can roll back an update that is paused by using the rolling-updates rollback subcommand. This stops the update from being applied to more instances, and instances already created with the new template will be recreated with the last template applied before the current update.

To roll back an update:

gcloud alpha compute rolling-updates rollback [UPDATE_ID] --zone [ZONE]

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

Continuing a rolling update

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

gcloud alpha compute rolling-updates resume [UPDATE_ID] --zone [ZONE]

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

Canceling a rolling update

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

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

gcloud alpha compute rolling-updates cancel [UPDATE_ID] --zone [ZONE]

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

Rolling updates and autoscaling

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

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

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. The Google APIs service account is different than the default Compute Engine service account and is identifiable using the email:

{project-number}@cloudservices.gserviceaccount.com

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 serviceAccountActor role, to create and manage instances in the instance group. The serviceAccountActor 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 serviceAccountActor 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.

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 root persistent disk, but the persistent disk already exists. By default, new root 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 root 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 root 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 mispelled a resource name.
    • You tried to attach additional non-root 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

Send feedback about...

Compute Engine Documentation