Working with managed instances

A managed instance is a data entity that represents the intended state for an actual virtual machine (VM) instance in a managed instance group (MIG). Read this document to learn how to reliably work with the managed instances in a MIG. For example, you might need to add, remove, update, or get information about a specific instance.

To ensure that your configuration changes aren't reverted by the MIG, it's important to use the methods that are described in this document. If you work outside the group's methods, the MIG will detect changes and might attempt to repair the group. For example, if you delete an instance in a group, the MIG might automatically recreate that instance according to the managed instance's specification.

Before you begin

• If you want to use the command-line examples in this guide, do the following:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• Create an instance group based on an instance template.

What is a managed instance?

A managed instance is a data entity within a MIG that contains the current status and intended state for an actual VM instance.

The current status of a managed instance includes the following fields:

• Instance lifecycle status—for example, RUNNING, STOPPING.
• Current action performed by the MIG on an instance—for example: RESTARTING, VERIFYING, NONE.
• Instance health state—for example, HEALTHY, UNHEALTHY.

A managed instance's intended state for an actual VM instance includes the following:

• Intended version, that is, the version name and instance template to be used for the instance.
• Preserved state of items (such as disks or metadata) to be preserved.

As shown in figure 1, for each managed instance in a MIG, the MIG keeps an actual VM up and running according to the managed instance's specification.

Figure 1. Relationship between managed instances and corresponding VMs.

Note: Various policies and actions create, delete, and modify the VM 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 actual 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.

To view the specifications of a managed instance, see Getting information about the managed instances in a MIG.

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. For more information about automatically scaling your MIG, see Autoscaling groups of instances.

Adding instances with specific names

If you have a system that depends on specific names, use the gcloud tool or API to add VMs with specific names to an existing MIG.

The names that you assign to these managed instances persist if the MIG recreates the VM. For more information about preserving the state of MIG instances, see stateful MIGs.

Limitations

If you create instances with specific names:

• You must turn off autoscaling during the instance creation process.
• You must set the MIG's update policy to be opportunistic.
• If you are updating a regional MIG:
  • You must disable proactive instance redistribution.
  • You can't select which zone to create the VM 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

Use the instance-groups managed create-instance command.

gcloud compute instance-groups managed create-instance INSTANCE_GROUP_NAME \
    --instance INSTANCE_NAME \
    [--region REGION | --zone ZONE]

Replace the following:

• INSTANCE_GROUP_NAME is the name of the regional or zonal MIG to add a new instance to.
• 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/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/createInstances
{
  "instances": [
    {
      "name": "INSTANCE_NAME_1"
    },
    {
      "name": "INSTANCE_NAME_2"
    }
  ]
}

Updating selected instances in a group

See Selectively updating instances in a MIG.

Deleting instances from a MIG

When you delete managed instances, the MIG reduces the targetSize of the group and deletes the corresponding VM instances.

If you set up a stateful MIG, then the MIG deletes the instances' preserved state configurations. The MIG also removes the instances from any target pools of which they are a member.

If the group is part of a backend service that has enabled connection draining, it can take up to an additional 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.

Deleting specific instances

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

Delete specific managed instances 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 Instance groups

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. In the Members section, from the list of instances select one or more instances that you want to delete.

4. Click Delete instance. The selected instances are deleted.

gcloud

To delete an instance with the gcloud tool, use the instance-groups managed delete-instances command.

gcloud compute instance-groups managed delete-instances INSTANCE_GROUP_NAME \
    --instances INSTANCE_NAME_1,INSTANCE_NAME_2 \ 
    [--region REGION | --zone ZONE]

The command returns the operation status per instance:

• SUCCESS is returned if the gcloud tool deleted the instance.
• FAIL is returned for all instances if any instance that you specify in the request is not a member of the group, if any member is already being deleted or abandoned, or if the request fails for any other reason.
• SKIPPED is returned only if you use the --skip-instances-on-validation-error flag and the instance is not a member of the group or is already being deleted or abandoned.
• MEMBER_NOT_FOUND is returned only for regional groups when the gcloud tool wasn't able to resolve the zone from the instance name.

If you anticipate that your deletion request might conflict with concurrent operations, use the --skip-instances-on-validation-error flag. This flag specifies whether the request should proceed even if the request includes instances that are not members of the group or that are already being deleted or abandoned—for example, instances that are being deleted by an autoscaler. By default, if you omit this flag and such an instance is specified in the request, the operation fails. The operation always fails if the request contains a badly formatted instance name or a reference to an instance that exists in a zone or region other than the group's zone or region.

For example, the following command requests deletion of four instances, but three of them are no longer in the group:

gcloud compute instance-groups managed delete-instances example-mig \
    --instances=example-instance-1,example-instance-2,example-instance-3,example-instance-4 \
    --region=us-central1 \
    --skip-instances-on-validation-error

In this example, three instances didn't pass validation, so they were skipped, while example-instance-3 was deleted:

Updated [https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/instanceGroupManagers/example-mig].
PROJECT          ZONE           INSTANCE               STATUS   VALIDATION_ERROR
example-project  us-central1-a  example-instance-1     SKIPPED  Cannot delete instance https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances/example-instance-1 that was already deleted.
example-project  us-central1-a  example-instance-2     SKIPPED  Cannot delete instance https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances/example-instance-2 that was already abandoned.
example-project  us-central1-a  example-instance-3     SUCCESS
example-project  us-central1-a  example-instance-4     SKIPPED  Cannot find instance https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances/example-instance-4.

If you omit the --skip-instances-on-validation-error flag and if any instance does not pass validation, then no instance is deleted:

gcloud compute instance-groups managed delete-instances example-mig \
    --instances=example-instance-1,example-instance-2,example-instance-3,example-instance-4 \
    --region=us-central1

Updated [https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/instanceGroupManagers/example-mig].
PROJECT          ZONE             INSTANCE              STATUS
example-project  us-central1-a    example-instance-1    FAIL
example-project  us-central1-a    example-instance-2    FAIL
example-project  us-central1-a    example-instance-3    FAIL
example-project  us-central1-a    example-instance-4    FAIL

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/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/deleteInstances

{
  "instances": [
    "zones/ZONE/instances/INSTANCE_NAME_1",
    "zones/ZONE/instances/INSTANCE_NAME_2"
   ]
}

If you anticipate that your deletion request might conflict with concurrent operations, use the skipInstancesOnValidationError field. This field specifies whether the request should proceed even if the request includes instances that are not members of the group or that are already being deleted or abandoned—for example, instances that are being deleted by an autoscaler. By default, if you omit this flag and such an instance is specified in the request, the operation fails. The operation always fails if the request contains a badly formatted instance name or a reference to an instance that exists in a zone or region other than the group's zone or region.

For example, the following request to delete 2 instances will succeed even if one of the instances is already deleted or being deleted:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/deleteInstances

{
 "instances": [
  "zones/ZONE/instances/INSTANCE_NAME_1",
  "zones/ZONE/instances/INSTANCE_NAME_2"
 ],
 "skipInstancesOnValidationError": true
}

You can view instances that were skipped in the operation by viewing the operation. For regional MIGs, use the regionOperations.get method. For zonal MIGs, use the zoneOperations.get method. Warnings are listed in the operation's warning field.

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 a VM 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 an additional 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 Instance groups

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. In the Members section, from 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 VM, use the instance-groups managed abandon-instances command.

gcloud compute instance-groups managed abandon-instances INSTANCE_GROUP_NAME \
    --instances INSTANCE_NAME_1,INSTANCE_NAME_2 \
    [--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/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/abandonInstances

{
 "instances": [
  "zones/ZONE/instances/INSTANCE_NAME_1",
  "zones/ZONE/instances/INSTANCE_NAME_2"
 ]
}

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

Use this method to update selected VMs so that they use the latest instance template and stateful configuration, if any. If you need to recreate all of the VMs 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 an additional 60 seconds after the connection draining duration has elapsed before the VM instance is removed or deleted.

Recreate selected VM 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 command.

gcloud compute instance-groups managed recreate-instances INSTANCE_GROUP_NAME \
    --instances INSTANCE_NAME_1,INSTANCE_NAME_2 \
    [--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/regions/REGION/instanceGroupManagers/INSTANCE_GROUP_NAME/recreateInstances

{
 "instances": [
  "zones/ZONE/instances/INSTANCE_NAME_1",
  "zones/ZONE/instances/INSTANCE_NAME_2"
 ]
}

After you make a request to recreate VM instances in a managed instance group, the new VMs 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.

Configuring stateful instances in a MIG

For more information, see Configuring stateful MIGs.

What's next

• Learn about Rolling out updates to managed instance groups.
• Learn about Applying machine type 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