Use the methods on this page to view information about yourmanaged instance groups (MIGs) and to view information about the virtual machine (VM) instances withineach MIG.

Before you begin

• Review thelimitations thencreate a group.
• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  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. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  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. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

View info about MIGs

You can retrieve information about groups themselves, for example, to inspectthe policies that are attached to the group and to check if the group isstable or undergoing changes. To get info about the VM instances within a MIG,seeView info about managed instances.

List MIGs

To get a list of your managed instance groups, use theconsole, thegcloud CLI,orREST.

gcloud compute instance-groups managed list

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers

GET https://compute.googleapis.com/compute/v1/projects/project-id/regions/region/instanceGroupManagers

View a MIG's properties

To view information about a specific MIG, including its policies (forexample, the group's autohealing and update policies), use theconsole, thegcloud CLI,orREST.

To view the group'sid value, you must use the gcloud CLI or theCompute Engine API.

gcloud compute instance-groups managed describeinstance-group \    [--zonezone | --regionregion]

gcloud compute instance-groups managed describeinstance-group --format="(autoscaler)"

GET https://compute.googleapis.com/compute/v1/projects/project-id/regions/region/instanceGroupManagers/instance-group

GET https://compute.googleapis.com/compute/v1/projects/project-id/regions/region/regionAutoscalers/mig_name

Check whether a MIG is stable

Several commands and requests create, delete, and modify instances in a managedinstance group. Those operations are returned asDONE after the group hasscheduled actions to create, delete, or update those instances. However, thisdoesn't mean that instances in the group have been created, deleted, orupdated until those underlying actions are complete. You mustverify the status of the group, or alternativelyverify the status of those instances.

A managed instance group is stable when all instances in the managed instancegroup are not undergoing any change, no future changes are scheduled for theinstances, and the group itself is not being modified.

You might need to know whether the group is stable when you have dependenciesthat rely on all instances in the group being healthy and serving. For example,you might want to start scheduling jobs, sending traffic, or assigning keyranges after you have confirmation that all the VMs are running and healthy.

Verify that all instances in a managed instance group are running and healthy bychecking the value of the group'sstatus.isStable field.

gcloud compute instance-groups managed describeinstance-group-name \    [--zonezone | --regionregion]

gcloud compute instance-groups managed wait-untilinstance-group-name \    --stable \    [--zonezone | --regionregion]Waiting for group to become stable, current operations: deleting: 4Waiting for group to become stable, current operations: deleting: 4...Group is stable

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

GET https://compute.googleapis.com/compute/v1/projects/project-id/regions/region/instanceGroupManagers/instance-group-name/get

status.isStable set tofalse indicates that changes are active, pending, orthat the MIG itself is being modified.

status.isStable set totrue indicates the following:

• None of the instances in the MIG are undergoing any type of change and thecurrentAction for all instances isNONE.
• No changes are pending for instances in the MIG.
• The MIG itself is not being modified.

Remember that the stability of a MIG depends on numerous factors because a MIGcan be modified in numerous ways. For example:

• You make a request to roll out a new instance template.
• You make a request to create, delete, resize or update instances in the MIG.
• Anautoscaler requests to resize theMIG.
• Anautohealerresource is replacing one or more unhealthy instances in the MIG.
• In a regional MIG, some of the instances are beingredistributed.

As soon as all actions are finished,status.isStable is set totrue againfor that MIG.

For individual VM instances, seeChecking the status of managed instances.

Check the repair configuration in a MIG

To check the repair configuration in a MIG, select one of the following options:

gcloud beta compute instance-groups managed describeinstance-group \    --format="(instanceLifecyclePolicy)" \    --zone=zone

  instanceLifecyclePolicy:    defaultActionOnFailure: DO_NOTHING    forceUpdateOnRepair: NO    onFailedHealthCheck: DEFAULT_ACTION    onRepair:      allowChangingZone: YES

GET https://compute.googleapis.com/compute/beta/projects/project_ID/zones/zone/instanceGroupManagers/instance_group

..."instanceLifecyclePolicy": {  "forceUpdateOnRepair": "NO",  "defaultActionOnFailure": "DO_NOTHING",  "onFailedHealthCheck": "DEFAULT_ACTION",  "onRepair": {    "allowChangingZone": "YES"  }}...

If the repairs are turned off and you want to turn them back on again, seeTurn on repairs or autohealing.

View historical autohealing operations

If you configured autohealing, then you canview past autohealing events.

Monitor rolling updates

If you initiated a rolling update, and want to know when the update is complete,then seeMonitoring updates.

View stateful configuration

If you configured astateful MIGand want to review your configuration, then seeViewing stateful configuration.

View details about the managed VM instances within a MIG

This section explains how to view various details about managed instances in aMIG.

List a MIG's managed instances

To view a list of the managed instances in a group, including their states andtemplates, use theconsole, thegcloud CLI,orREST.

gcloud compute instance-groups managed list-instancesinstance-group \    [--zonezone | --regionregion]

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

GET https://compute.googleapis.com/compute/v1/projects/project-id/regions/region/instanceGroupManagers/instance-group

Check the status of managed instances

Several commands and requests create, delete, and modify instances in a managedinstance group. Those operations are returned asDONE after the group hasscheduled actions to create, delete, or update those instances. However, thisdoesn't mean that instances in the group have been created, deleted, orupdated until those underlying actions are complete. You must verify the statusof those instances, or alternatively verify thestatus of the group itself.

Use the Google Cloud CLI or REST to see details about the instancesin a managed instance group. Details include instance status and current actionsthat the group is performing on its instances.

gcloud compute instance-groups managed list-instancesINSTANCE_GROUP_NAME \    [--zone=ZONE | --region=REGION]

NAME: vm-instances-9pk4ZONE: us-central1-fSTATUS:HEALTH_STATE:ACTION: CREATINGINSTANCE_TEMPLATE: my-new-templateVERSION_NAME:LAST_ERROR:NAME: vm-instances-h2r1ZONE: us-central1-fSTATUS: STOPPINGHEALTH_STATE:ACTION: DELETINGINSTANCE_TEMPLATE: my-old-templateVERSION_NAME:LAST_ERROR:

gcloud compute instance-groups managed describe-instanceINSTANCE_GROUP_NAME \    --instanceINSTANCE_NAME \    [--zone=ZONE | --region=REGION]

currentAction: NONEid: '6789072894767812345'instance: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/instances/example-mig-hz41instanceStatus: RUNNINGname: example-mig-hz41preservedStateFromConfig:  metadata:    example-key: example-valuepreservedStateFromPolicy:  disks:    persistent-disk-0:      autoDelete: NEVER      mode: READ_WRITE      source: https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/disks/example-mig-hz41version:  instanceTemplate: https://www.googleapis.com/compute/v1/projects/example-project/global/instanceTemplates/example-template

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/INSTANCE_GROUP_NAME/listManagedInstances

{  "managedInstances": [    {      "instance": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-f/instances/vm-instances-prvp",      "instanceStatus": "RUNNING",      "currentAction": "REFRESHING",      "id": "5317605642920955957",      "version": {        instanceTemplate": "https://www.googleapis.com/compute/v1/projects/example-project/global/instanceTemplates/example-template"      },      "name": "vm-instances-prvp"    },    {      "instance": "https://www.googleapis.com/compute/v1/projects/example-project/zones/us-central1-f/instances/vm-instances-w2t5",      "instanceStatus": "RUNNING",      "currentAction": "REFRESHING",      "id": "2800161036826218547",      "version": {        "instanceTemplate": "https://www.googleapis.com/compute/v1/projects/example-project/global/instanceTemplates/example-template"      },      "name": "vm-instances-w2t5"    }  ]}

To see a list of validinstanceStatus field values, seeVM instance lifecycle.

If an instance is undergoing some type of change, the managed instance groupsets the instance'scurrentAction field to one of the following actions tohelp you track the progress of the change. Otherwise, thecurrentAction fieldis set toNONE.

PossiblecurrentAction values are:

• ABANDONING. The instance is being removed from the MIG.
• CREATING. The instance is in the process of being created.
• CREATING_WITHOUT_RETRIES. The instance is being created without retries; ifthe instance isn't created on the first try, the MIG doesn't try to replacethe instance again.
• DELETING. The instance is in the process of being deleted.
• RECREATING. The instance is being replaced.
• REFRESHING. The instance is being removed from its current target pools andbeing readded to the list of current target pools (this list might be thesame or different from existing target pools).
• RESTARTING. The instance is in the process of being restarted using thestop andstart methods.
• RESUMING. The instance is in the process of being resumed after beingsuspended.
• STARTING. The instance is in the process of being started after beingstopped.
• STOPPING. The instance is being stopped.
• SUSPENDING. The instance is being suspended.
• VERIFYING. The instance has been created and is in the process of beingverified.
• NONE. No actions are being performed on the instance.

To check if the group as a whole is stable or is undergoing changes, seeChecking the status of the group.

Check health states

If you have configured autohealing for your managed instance group, you canreview the health state of each VM. SeeChecking health status.

List instance errors

If your managed instances encountered errors, you can view those errorsto diagnose and mitigate the cause.

Use the Google Cloud console, the gcloud CLI, or REST tolist errors.

gcloud compute instance-groups managed list-errorsinstance-group-name \    [--zonezone | --regionregion]

gcloud compute instance-groups managed list-errors example-group \    --region us-west1

INSTANCE_URL                                                                                        ACTION    ERROR_CODE      ERROR_MESSAGE                                                                                     TIMESTAMP                      INSTANCE_TEMPLATE                                                                                                            VERSION_NAMEhttps://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/igm-1-v0hl  CREATING  QUOTA_EXCEEDED  Instance 'igm-1-v0hl' creation failed: Quota 'CPUS' exceeded.  Limit: 1.0 in zone us-central1-a.  2019-07-11T07:44:40.156-07:00  https://www.googleapis.com/compute/v1/projects/my-project/global/instanceTemplates/instance-template-1https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances/igm-1-qp3d  CREATING  QUOTA_EXCEEDED  Instance 'igm-1-qp3d' creation failed: Quota 'CPUS' exceeded.  Limit: 1.0 in zone us-central1-a.  2019-07-11T07:44:40.081-07:00  https://www.googleapis.com/compute/v1/projects/my-project/global/instanceTemplates/instance-template-1...

GET https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instanceGroupManagers/instance-group-name/listErrors&maxResults=100

{ "items": [  {   "error": {    "code": "QUOTA_EXCEEDED",    "message": "Instance 'example-mig-m1sz' creation failed: Quota 'CPUS' exceeded.  Limit: 50.0 in zone us-central1-c."   },   "timestamp": "2019-01-03T18:47:28.457-08:00",   "instanceDetails" : {    "instance": "zones/us-central1-c/instances/example-mig-m1sz",    "action": "CREATING",    "version": {     "name": "example-version-name",     "instanceTemplate": "global/instanceTemplates/example-template",    }   }  } ], ... "nextPageToken": "Ch0yMDE5LTA3LTI5VDExOjA4OjA2LjYxMi0wNzowMBJ5aHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vY29tcHV0ZS9zdGFnaW5nX2FscGhhL3Byb2plY3RzL215cnpha2VyZXltcy1zdGFnaW5nL3pvbmVzL3VzLWNlbnRyYWwxLWlyMS9pbnN0YW5jZXMvaWdtLTEtcXAzZA=="}

The list of possible errors includes, but is not limited to, the followingexamples:

• A new instance cannot be created due to:
  • Unavailability of preemptible capacity.
  • Lack of quota, for example, for CPUs in a given region.
  • The limit on the number of VM instances was reached for the networkassociated with the group.
  • The disk image specified in the instance template'sproperties.disks[].initializeParams.sourceImage field was deleted, or itspermissions have changed.
  • The credit card on the billing account associated with the project refused apayment.
• An existing instance cannot be deleted because:
  • The service account that group uses doesn't havecompute.instances.deletepermission.
  • Too many concurrent deletions were requested, exceeding rate limits.
• An instance cannot be added to a target pool because the target pool wasdeleted.

After inspecting such errors, you can mitigate them. For example:

• Move your workload to a different zone that has preemptible capacity.
• Request a quota increase in a given region.
• Add thecompute.instances.delete permission to the service account used bythe group.

If an action that is triggered by a managed instance group fails (for example,if an autoscaler encounters an error when attempting to increase the group'ssize), the group might immediately retry that action. If the last immediateretry attempt fails, the MIG records the error, and you can view the errorbylisting instance errors. After some backoff time,the group again retries the failed action. If the error persists, it might berecorded multiple times.

Compute Engine retains the most recent 500 errors for the last 8 days evenif the underlying instances no longer exist or couldn't be created.

Check if a VM instance is part of a MIG

To check if a specific VM is a member of a group, you can usethe console or REST.

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

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

Even if youabandonthe instance, the VM will still have these metadataentries, unless you manually remove them.

For example, if there was an VM namedrandom-instance-biy and you wantedto know whether the VM was created by a managed instance group, you candescribe the instance and look for the metadata keys. For example:

gcloud compute instances describe random-instance-biy \    --zone us-central1-f

gcloud CLI returns a response similar to:

canIpForward: falsecpuPlatform: Intel Ivy BridgecreationTimestamp: '2016-08-24T14:11:38.012-07:00'...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

View the preserved state of a managed instance

If you configured astateful MIGand want to view thepreserved stateof each managed instance, seeViewing stateful configuration and preserved state.

What's next

• Learn more aboutmanaged instance groups.
• Create an instance template that you canuse tocreate a managed instance group.