Work with managed instances

A managed instance group (MIG) creates each of its managed instances based on the configuration components that you use: instance template, optional all-instances configuration, and optional stateful configuration.

Each managed instance is a data entity that represents the intended state for an actual virtual machine (VM) instance in a 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 view 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 to modify a MIG's VMs, the MIG might or might not detect that those VMs are no longer using the group's intended configuration, and you might experience unexpected results. For example, if you delete or update a VM in a MIG by using the instances API instead of the required instance group manager API, the MIG will not be aware of your intent and, at any time in the future, the MIG might automatically attempt to recreate or revert that VM according to the MIG's configuration.

Before you begin

  • Review the limitations then create a group.
  • Set up authentication.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

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.

Based on your configuration, the MIG autogenerates managed instances, which correspond to actual VM instances that a MIG maintains on your behalf.

Figure 1. Relationship between managed instances and corresponding VMs.

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

Adding instances to a MIG

To add more instances to a MIG, you can:

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 set the size of 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, you can add VMs with those names to an existing MIG. The names that you assign to these managed instances persist if MIG recreates the VM. For more information, see Creating instances with specific names in MIGs

For more information about preserving the state of MIG instances, see stateful 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.

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, you can:

Updating VM configuration in a MIG

If you need to change the configuration of VMs in a MIG—for example, to modify the boot disk or machine type, add disks, or change other VM properties—see Updating VM configuration in a MIG.

Recreating instances in a MIG

Use this method to update selected VMs so that they use the group's latest VM configuration components. 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 CLI, or REST.

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]

REST

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.

The recreate operation preserves the VM instance name, but the instance creation timestamp might not change. To confirm that the recreate operation has created a new instance when the instance creation timestamp has not changed, check the creation timestamp of the boot disk attached to that instance.

Viewing information about instances in a MIG

See Viewing info about the managed instances in a MIG.

Configuring stateful instances in a MIG

See Configuring stateful MIGs.

What's next