Working with managed instances

You control a managed instance group (MIG) and its virtual machine (VM) instances as a single entity. For example, you can set autohealing, autoscaling, and auto-updating policies on the group. Based on your specifications, the MIG automatically acts on its instances to achieve the intended state.

If you need to act on specific managed instances in a MIG, for example, to create or delete instances with specific names, you must still act on those instances through the group entity. For example, use the instanceGroupManager or regionInstanceGroupManager API methods.

If you act on managed instances using methods outside of the group's methods, your actions might conflict with the group's actions. For example, if you delete an instance that belongs to a group, but you don't use the group's instance delete methods, the MIG might automatically recreate that instance according to the group's specifications.

Note: Various policies and actions create, delete, and modify the instances in a MIG. Those operations are returned as DONE after the group has scheduled actions to create, delete, or update those instances. However, this doesn't mean that the instances in the group have been created, deleted, or updated until those underlying actions are complete. You must verify the status of the group, or verify the status of those instances.

Before you begin

• If you want to use the API examples in this guide, set up API access.
• If you want to use the command-line examples in this guide, install the gcloud command-line tool.
• Create an instance group based on an instance template.

Adding instances to a MIG

To add more instances to a MIG, you can:

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

To verify that newly added instances are up and running, verify the status of the group, or verify the status of the managed instances.

Manual resizing

If a managed instance group isn't already set to automatically scale, you can resize the group manually to change the number of instances in the group. See Manually resizing a MIG.

Autoscaling

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 automatically scale your MIG, see Autoscaling groups of instances.

Adding instances with specific names (beta)

Beta

This feature is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

If you have a system that depends on specific names, use the gcloud tool or API to create new instances with those names. For regional MIGs, use the regional API method.

The names that you assign to these managed instances persist if the instance is recreated.

Limitations

If you create instances with specific names:

• Autoscaling must be turned off during the instance creation process.
• The MIG's update policy must be opportunistic.
• If you are updating a regional MIG:
  • Proactive instance redistribution must be turned off.
  • You can't select which zone to create the instance in.
• You can't use duplicate VM instance names within a project.

Permissions required for this task

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

• compute.instanceGroupManagers.update on the managed instance group

gcloud

gcloud beta compute instance-groups managed create-instance instance-group-name \
    --instance managed-instance-name \
    [--region region | --zone zone]

Where:

• instance-group-name is the name of the regional or zonal MIG to add a new instance to.
• managed-instance-name is the name you want to assign to the new instance.

API

In the API, make a POST request to the regionInstanceGroupManagers.createInstances method. For a zonal managed instance group, use the instanceGroupManagers.createInstances method. In the request body, include the instances field with names for one or more instances.

POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/createInstances
{
  "instances": [
    {
      "name": "instance-name-1"
    },
    {
      "name": "instance-name-2"
    }
  ]
}

Updating selected instances in a group

See Rolling out updates to MIGs.

Deleting instances from a MIG

When you delete managed instances, the MIG reduces the targetSize of the group and deletes the corresponding VM instances. The MIG removes the instances from any target pools of which they are a member. If you set up a stateful MIG, then the MIG also deletes the instances' preserved state configurations.

Deleting instances from a managed instance group doesn't 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.

To delete a managed instance, and therefore delete its corresponding VM instance, you can:

• Resize the MIG. The MIG chooses which instances to delete.
  • Manually resize the MIG.
  • Use autoscaling for stateless applications.
• Delete the whole group.
• Delete or abandon specific instances explicitly.

Delete specific instances

You can delete specific 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 doesn't 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 Console, the gcloud command-line tool, or the API.

Permissions required for this task

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

• compute.instanceGroupManagers.update on the managed instance group

Console

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

   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 the gcloud tool, use the instance-groups managed delete-instances subcommand:

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

API

In the API, make a POST request to the regionInstanceGroupManagers.deleteInstances method. For a zonal managed instance group, use the instanceGroupManagers.deleteInstances method.

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

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

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 the group or verify the status of the managed instances.

Abandoning instances from a MIG

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 doesn't 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 Console, the gcloud tool, or the API.

Permissions required for this task

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

• compute.instanceGroupManagers.update on the managed instance group

Console

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

   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-name \
    --instances example-i3n2,example-z2x9 \
    [--region region | --zone zone]

API

In the API, make a POST request to the regionInstanceGroupManagers.abandonInstances method. For a zonal managed instance group, use the instanceGroupManagers.abandonInstances method.

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

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

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 the group or verify the status of the managed instances.

Recreating instances in a MIG

Recreating an instance deletes the specified instance and creates a new instance 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 tool, or the API.

Permissions required for this task

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

• compute.instanceGroupManagers.update on the managed instance group

gcloud

Use the instance-groups managed recreate-instances subcommand.

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

API

In the API, make a POST request to the regionInstanceGroupManagers.recreateInstances method. For a zonal managed instance group, use the instanceGroupManagers.recreateInstances method.

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

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

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 the group or verify the status of the managed instances.

Getting information about instances in a MIG

See Getting info about the managed instances in a MIG.

What's next

• Learn about Rolling out updates to managed instance groups.
• Learn about Applying instance sizing recommendations for MIGs.
• Try a tutorial:
  • Using autohealing for highly available applications
  • Using load balancing for highly available applications
  • Using autoscaling for highly scalable applications