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

Limitations

  • If you want to use load balancing with a regional MIG, the following limitations apply:
    • You cannot use the maxRate balancing mode.
    • If you use an HTTP(S) load balancing scheme with a regional MIG, you must choose the maxRatePerInstance or maxUtilization balancing mode.

Adding 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 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.

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

Console

  1. Go to the Load balancing page in the Cloud Console.

    Go to the Load balancing page

  2. Click the name of the backend service to which you are adding the managed instance group.
  3. Click Edit.
  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

With the gcloud command-line tool, use the add-backend command:

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

Additional parameters are required depending on the balancing mode of the managed instance group. For more information, see the add-backend command in the SDK.

API

To add a backend service using the REST API, see backendServices.

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 the 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 proxy load balancers 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 proxy load balancers. Named ports do not control network or firewall resources in Compute Engine.

Using 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 for the same application.

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

Configuring the instance group

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 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, if ports 10, 20, and 80 are for the same application, you can assign name1 to all of those ports. Additionally, you might assign two names, name2 and name3 to port 8080. Finally, you might assign port 9000 to name4, as in the following example:

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
  }
 ]
}

For example, if ports 10, 20, and 80 are for the same application, you can assign name1 to all of those ports. Additionally, you might assign two names, name2 and name3 to port 8080. Finally, you might assign port 9000 to name4, 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": 10
  },
  {
   "name": "name1",
   "port": 20
  }
  {
   "name": "name1",
   "port": 80
  }
  {
   "name": "name2",
   "port": 8080
  }
  {
   "name": "name3",
   "port": 8080
  }
  {
   "name": "name4",
   "port": 9000
  }
 ]
}

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]

In addition to the instance group configuration, you must also configure the backend service. For example, suppose you set the named port on an instance group with the name my-service-name and the port 8888:

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 with the --port-name on the backend service set to my-service-name:

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

What's next