Add an instance group to a load balancer

This page describes how to add an existing managed instance group (MIG) to thebackend service or target pool of a load balancer.

A load balancer distributes user traffic which helps in reducing the risk ofexperiencing performance issues in your application. Cloud Load Balancingusesinstance groups, both managed andunmanaged, to serve traffic. Depending on thetype of load balancer you areusing, you can add instance groups to a target pool or backend service.

For information aboutcreating a specific type of load balancer with a MIG backend, see theCloud Load Balancingdocumentation.

Before you begin

Add a managed instance group to a backend service

A backend service is necessary for creating most types of load balancers.

A backend service can contain multiple backends. An instance group is a type ofbackend. The instances in the instance group respondto traffic from the load balancer. The backend service in turn knows whichinstances it can use, how much traffic they can handle, and how much trafficthey are currently handling. In addition, the backend service monitors healthchecking and does not send new connections to unhealthy instances.

Use these instructions to add a managed instance group to a backend service.

Console

  1. Go to the Load balancing page in the Google Cloud console.

    Go to the Load balancing page

  2. Click the name of the backend service to which you are adding the managedinstance group.
  3. ClickEdit.
  4. Click+Add backend.
  5. Select the instance group you want to add.
  6. Edit any optional settings you want to change.
  7. Save your changes.

gcloud

Use theadd-backend command:

    gcloud compute backend-services add-backendBACKEND_SERVICE_NAME \        --instance-group=INSTANCE_GROUP \        [--instance-group-region=INSTANCE_GROUP_REGION | --instance-group-zone=INSTANCE_GROUP_ZONE] \        --balancing-mode=BALANCING_MODE

Balancing mode support differs based on the type of load balancer. For thecomplete list, seeBalancing mode available for each load balancer.

Additional parameters are required depending on the balancing mode of themanaged instance group. For more information, see theadd-backend commandin the SDK.

REST

To add a backend service using the REST API, seebackendServices.

Limitations

Load balancingwith a regional MIG doesn't support themax-rate target capacity inRATE andUTILIZATION balancing modes. To learn more about the usageguidelines for each load balancer, seeBalancing modes and target capacity settings.

Add a managed instance group to a target pool

A target pool is an object that contains one or more virtual machineinstances. A target pool is used inexternal passthrough Network Load Balancers, where theload balancer forwards user requests to the attached target pool. The instancesthat 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 areadded or removed from the instance group, the target pool is also automaticallyupdated with the changes.

Before you can add a managed instance group to a target pool, the target poolmust exist. For more information, see the documentationforAdding a target pool.

To add an existing managed instance group to a target pool, follow theseinstructions. This causes all VM instances that are part of the managed instancegroup to be added to the target pool.

Note: While the instance is being added, the instance'scurrentAction will change toREFRESHING.You can not use the instance while it is currentlyREFRESHING but youcan use thewait-until-stablecommand to poll the instance until it becomes stable.

Console

  1. Go to the Target Pools page in the Google Cloud console.

    Go to the Target Pools page

  2. Click the target pool you want to add the instance group to.
  3. Click theEdit button.
  4. Scroll down to theVM instances section and click onSelect instance groups.
  5. Select an instance group from the drop-down menu.
  6. Save your changes.

gcloud

Use theset-target-pools command:

gcloud compute instance-groups managed set-target-poolsINSTANCE_GROUP \        --target-poolsTARGET_POOL,..

where:

  • INSTANCE_GROUP is the name of the instance group.
  • TARGET_POOL,.. is the name of one or more target pools toadd this instance group to.

REST

Call thesetTargetPools method for aregional MIGorzonal MIG.For example:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/regionInstanceGroupManagers/INSTANCE_GROUP/setTargetPools

where:

  • PROJECT_ID is the project ID for this request.
  • REGION is the region 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 wantto add this group. For example:

{  "targetPools": [    "regions/us-central1/targetPools/example-targetpool-1",    "regions/us-central1/targetPools/example-targetpool-2"  ]}

Assign named ports to managed instance groups

Named ports are key-value pairs that represent a port's name and number. Theport name represents a name of a service or application. The port numberrepresents the port that service or application runs on.

Named ports are used by Cloud Load Balancing. Load balancersthat act as proxies subscribe to a single named port in their backend serviceconfiguration. The port's name is translated to a port number based on the namedport's mapping of each instance group backend.

For example, a backend service can subscribe to a port that is namedhttp-port.The backend instance group can have a port namedhttp-port:80. The backendinstance group instructs the load balancer to send traffic to a VM in the groupon port 80 using a protocol (such as TCP). The protocol is defined in the loadbalancer's backend service.

Named ports are simple metadata used byproxy load balancers. Namedports do not control network or firewall resources in Compute Engine.

Multiple port numbers for a named port

You can assign multiple ports for each service name.You can also assign multiple service names for each port.

Keep in mind the following points:

  • Traffic is balanced between all ports with the same port name.
  • A given backend service can only forward traffic to one named port at a time.

  • If you use multiple port numbers for a named port, the ports must all be forthe same application.

    For example,http:80,http:8080 works, buthttp:80,http:443doesn't work because port 80 generally doesn't support TLS.

You can assign multiple named ports in an instance group. To illustrate,consider an example backend service that subscribes to the named porthttp-port, and that has two backend instance groups:

  • instance-group-a with a named port ofhttp-port:80
  • instance-group-b with a named port ofhttp-port:79

This backend service sends traffic to port 80 for VMs ininstance-group-a andport 79 for VMs ininstance-group-b.

When you add the same instance group to multiple backend services (for multipleload balancers) and the instance group serves different ports on each loadbalancer, don't add all the port numbers to a single named port. Instead createa unique named port and map it to a set of ports that each backend serviceshould serve.

For example, suppose you have three applications, each with its own loadbalancer. Each application has its own port number: 81 forapp1, 82forapp2, and 83 forapp3. Assuming that all three backend services areusing a common instance group, assign the named ports for this instance groupas[app1:81, app2:82, app3:83].

Named ports and health checks

For a named port with multiple port numbers on a backend service to work in anexternal Application Load Balancer or an internal Application Load Balancer, the health check must have the--use-serving-port flag instead of a specific port number. This option is notavailable in the Google Cloud console. To set--use-serving-port, you must use theGoogle Cloud CLI or the API.

For example, suppose you have an application that load balances the traffic onthree different ports (81, 82, 83) on the same backend service with a singleinstance group. You can assign the ports for this instance groups as[app:81,82, 83]. The health check in this scenario must have the--use-serving-portflag.

For more information, see theload balancing health checkdocumentation.

Named ports and firewall rules

Named ports donot create or modify Google Cloudfirewallrules. To permit traffic to backend VMs, you must stillcreate the necessary firewall rules.

Named ports and backend services

In addition to the instance group configuration, you must also configurethe backend service. For example, suppose you set the named port on an instancegroup with the namemy-service-name and the port8888:

gcloud compute instance-groups set-named-ports my-unmanaged-ig \    --named-ports=my-service-name:8888

Then you must refer to the named port in the backend service configuration withthe--port-name on the backend service set tomy-service-name:

gcloud compute backend-services update my-backend-service \    --port-name=my-service-name

Create named ports

Permissions required for this task

To perform this task, you must have the followingpermissions:

  • compute.instanceGroups.update on the instance group

Console

  1. In the Google Cloud console, go to theInstance groups page.

    Go to Instance groups

  2. Click the name of the instance group where you want to specify namedports. A page opens with the instance group properties.
  3. ClickEdit to modify this managed instance group.
  4. In thePort mapping section, clickAdd port,and enter the desired port name and the port numbersthat you want to associate with that name. If you need more entries,clickAdd port again.
  5. ClickSave to save your changes and apply the named ports to theinstances in the managed instance group.

gcloud

For managed instance groups, set one or more named ports using theinstance-groups managed set-named-ports command.For unmanaged groups, use theinstance-groups set-named-ports command.

gcloud compute instance-groups managed set-named-portsINSTANCE_GROUP \      --named-portsPORT_NAME:PORT,PORT_NAME:PORT

For example:

gcloud compute instance-groups managed set-named-portsINSTANCE_GROUP \      --named-ports name1:80,name2:8080

To assign multiple ports to each service name or multiple names for eachservice, create more than one entry for each name or port. For example, ifports10,20, and80 are for the same application, you can assignname1 to all of those ports. Additionally, you might assign two names,name2 andname3 to port8080. Finally, you might assign port9000 toname4, as in the following example:

gcloud compute instance-groups managed set-named-portsINSTANCE_GROUP \      --named-ports name1:10,name1:20,name1:80,\                    name2:8080,name3:8080,\                    name4:9000

Check the named ports assignments for a managed instance group using theget-named-ports command:

gcloud compute instance-groups managed get-named-portsINSTANCE_GROUP
NAME  PORTname1 10name1 20name1 80name2 8080name3 8080name4 9000

REST

TheinstanceGroupManagers APIdoesn't offer asetNamedPorts API method. Instead, use theinstanceGroups APIto perform this task.

Construct a request to theinstanceGroups API and include the name ofthe instance group. Obtain the currentfingerprint value for the instancegroup bygetting information about a specific group.Include thefingerprint and one or morenamedPorts value pairs in therequest body:

POST https://compute.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, if ports10,20, and80 are for the same application, youcan assignname1 to all of those ports. Additionally, you might assign twonames,name2 andname3 to port8080. Finally, you might assign port9000 toname4, as in the following example:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-group/setNamedPorts{   "fingerprint": "42WmSpB8rSM=",   "namedPorts": [      {       "name": "name1",       "port": 8080      },      {       "name": "name2",       "port": 9000      }   ]}

To assign multiple ports to each service name, create multiple entriesfor that service name. For example, you can assign ports10,20, and80 toname1. Also assign port8080 toname2.

POST https://compute.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 instancegroup, construct aGET request that points to the group:

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

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-09 UTC.