Adding an instance group to a load balancer

Google Cloud load balancing uses instance groups, both managed and unmanaged, to serve traffic. Depending on the type of load balancer you are using, you can add instance groups to a target pool or backend service. To learn more about load balancing, see Choosing a load balancer.

To learn more about instance groups, read the Instance groups overview.

Before you begin

Adding a managed instance group to a backend service

A backend service is necessary for creating an HTTP(S), SSL Proxy, TCP proxy, or internal load balancer. A backend service can contain multiple backends. An instance group is a type of backend. The instances in the instance group respond to traffic from the load balancer. The backend service in turn knows which instances it can use, how much traffic they can handle, and how much traffic they are currently handling. In addition, the backend service monitors health checking and does not send new connections to unhealthy instances.

For instructions to add an instance group to a backend service, read Adding instance groups to a backend service.

Adding a managed instance group to a target pool

A target pool is an object that contains one or more virtual machine instances. A target pool is used in Network Load Balancing, where a network load balancer forwards user requests to the attached target pool. The instances that 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 are added or removed from the instance group, the target pool is also automatically updated with the changes.

Before you can add a managed instance group to a target pool, the target pool must exist. For more information, see the documentation for Adding a target pool.

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

Console

  1. Go to the Target Pools page in the Cloud Console.

    Go to the Target Pools page

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

gcloud

With the gcloud command-line tool, use the set-target-pools command:

gcloud compute instance-groups managed set-target-pools [INSTANCE_GROUP] \
        --target-pools [TARGET_POOL,..] [--zone ZONE]

where:

  • [INSTANCE_GROUP] is the name of the instance group.
  • [TARGET_POOL] is the name of one or more target pools to add this instance group to.
  • [ZONE] is the zone of the instance group.

API

In the API, make a POST request to the following URI:

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instanceGroupManagers/[INSTANCE_GROUP]/setTargetPools

where:

  • [PROJECT_ID] is the project ID for this request.
  • [ZONE] is the zone 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 want to add this group. For example:

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

Assigning named ports to managed instance groups

Named ports are key-value pairs that represent a service name and the port number that the service runs on. Named ports are used by load balancing services to direct traffic to specific ports on individual instances. For example, if you set a named port as http:80 and then configure your backend service to send traffic to a port named http, the load balancer forwards traffic to port 80 of individual instances that are part of the instance group.

Named ports are simple metadata used by load balancing. Named ports do not control network or firewall resources in Compute Engine.

You can assign multiple ports for each service name and multiple service names for each port. However, keep in mind that a given backend service can only forward traffic to one named port at a time.

Console

  1. Go to the Instance groups page in the Cloud Console.

    Go to the Instance groups page

  2. Click the name of the instance group where you want to specify named ports. A page opens with the instance group properties.
  3. Click Edit group to modify this managed instance group.
  4. Click Specify port name mapping to expand the named ports options.
  5. Click Add item, and enter the desired port name and the port numbers that you want to associate with that name. If you need more entries, click Add item again to add more entries.
  6. Click Save to save your changes and apply the named ports to the instances in the managed instance group.

gcloud

Set one or more named ports using the set-named-ports command:

gcloud compute instance-groups managed set-named-ports [INSTANCE_GROUP] \
      --named-ports [PORT_NAME]:[PORT],[PORT_NAME]:[PORT]

For example:

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

To assign multiple ports to each service name or multiple names for each service, create more than one entry for each name or port. For example, assign name1 to ports 10, 20, and 80. Then, assign both name2 and name3 to port 8080. Finally, assign port 9000 to name4.

gcloud compute instance-groups managed set-named-ports [INSTANCE_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 the get-named-ports command:

gcloud compute instance-groups managed get-named-ports [INSTANCE_GROUP]
NAME  PORT
name1 10
name1 20
name1 80
name2 8080
name3 8080
name4 9000

API

The instanceGroupManagers API doesn't offer a setNamedPorts API method. Instead, use the instanceGroups API to perform this task.

Construct a request to the instanceGroups API and include the name of the instance group. Obtain the current fingerprint value for the instance group by getting information about a specific group. Include the fingerprint and one or more namedPorts value pairs in the request 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:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instanceGroups/example-group/setNamedPorts

{
 "fingerprint": "42WmSpB8rSM=",
 "namedPorts": [
  {
   "name": "name1",
   "port": 80
  },
  {
   "name": "name2",
   "port": 8080
  }
 ]
}

To assign multiple ports to each service name, create multiple entries for that service name. For example, you can assign ports 10, 20, and 80 to name1. Also assign port 8080 to name2.

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 instance group, construct a GET request that points to the group:

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

What's next