Setting up custom header and query parameter-based routing for external HTTP(S) load balancers

Setting up query parameter-based routing

This example demonstrates using query parameters to do A/B testing by matching on the query string.

Adding two backend instance groups

For routing to be useful, you must have multiple backends.

To set up two backends, your VMs need to be in two instance groups. This guide describes how to create managed instance groups with Linux VMs that have Apache running and then set up load balancing.

The managed instance groups provide VMs running the backend servers of an external HTTP load balancer. For demonstration purposes, backends serve their own hostnames.

For simplicity, the backends reside in the same region. If you want a multi-region setup, you must have an instance template setup for the second region.

Console

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

    Go to the Instance Groups page

  2. Click Create instance group.
  3. Choose New managed instance group on the left.
  4. For the Name, enter first-example-ig.
  5. Under Location, select Single zone.
  6. For the Region, select your preferred region. This example uses us-east1.
  7. For the Zone, select us-east1-b.
  8. Under Instance template, select Create a new instance template.
  9. For the Name, enter lb-backend-template.
  10. Ensure that the Boot disk is set to a Debian image, such as Debian GNU/Linux 9 (stretch). These instructions use commands that are only available on Debian, such as apt-get.
  11. Under Management, security, disks, networking, sole tenancy, on the Management tab, insert the following script into the Startup script field.

    #! /bin/bash
    apt-get update
    apt-get install apache2 -y
    a2ensite default-ssl
    a2enmod ssl
    vm_hostname="$(curl -H "Metadata-Flavor:Google" \
    # See https://cloud.google.com/compute/docs/storing-retrieving-metadata#querying
    http://169.254.169.254/computeMetadata/v1/instance/name)"
    echo "Page served from: $vm_hostname" | \
    tee /var/www/html/index.html
    
  12. Under Networking, add the network tags: allow-health-check

  13. Click Save and continue.

  14. Under Number of instances, enter 2.

  15. Under Autoscaling mode, select Don't autoscale.

  16. Click Create to create the new instance group.

Create another managed instance group like this one. Name the second one second-example-ig, and base it on the lb-backend-template template.

gcloud

  1. Create the template.

    gcloud compute instance-templates create lb-backend-template \
       --region=us-east1 \
       --network=default \
       --subnet=default \
       --tags=allow-health-check \
       --image-family=debian-9 \
       --image-project=debian-cloud \
       --metadata=startup-script='#! /bin/bash
         apt-get update
         apt-get install apache2 -y
         a2ensite default-ssl
         a2enmod ssl
         vm_hostname="$(curl -H "Metadata-Flavor:Google" \
         # See https://cloud.google.com/compute/docs/storing-retrieving-metadata#querying
         http://169.254.169.254/computeMetadata/v1/instance/name)"
         echo "Page served from: $vm_hostname" | \
         tee /var/www/html/index.html
         systemctl restart apache2'
    
  2. Create the first managed instance group based on the template.

    gcloud compute instance-groups managed create first-example-ig \
       --template=lb-backend-template --size=2 --zone=us-east1-b
    
  3. Create the second managed instance group based on the template.

    gcloud compute instance-groups managed create second-example-ig \
       --template=lb-backend-template --size=2 --zone=us-east1-c
    

Configuring a firewall rule

In this example, you create the fw-allow-health-check firewall rule. This is an ingress rule that allows traffic from the Google Cloud health checking systems (130.211.0.0/22 and 35.191.0.0/16). This example uses the target tag allow-health-check to identify the VMs.

Console

  1. Go to the Firewalls page in the Google Cloud Console.
    Go to the Firewalls page
  2. Click Create firewall rule to create the second firewall rule:
  3. Enter a Name of fw-allow-health-check.
  4. Under Network, select Default.
  5. Under Targets, select Specified target tags.
  6. Populate the Target tags field with allow-health-check.
  7. Set Source filter to IP ranges.
  8. Set Source IP ranges to 130.211.0.0/22 and 35.191.0.0/16.
  9. Under Protocols and ports, select Specified protocols and ports.
  10. Select the checkbox next to tcp and type 80 for the port numbers.
  11. Click Create.

gcloud

gcloud compute firewall-rules create fw-allow-health-check \
    --network=default \
    --action=allow \
    --direction=ingress \
    --source-ranges=130.211.0.0/22,35.191.0.0/16 \
    --target-tags=allow-health-check \
    --rules=tcp

Reserving an external IP address

Now that your instances are up and running, set up a global static external IP address that your customers use to reach your load balancer.

Console

  1. Go to the External IP addresses page in the Google Cloud Console.
    Go to the External IP addresses page
  2. Click Reserve static address to reserve an IPv4 address.
  3. Assign a Name of lb-ipv4-1.
  4. Set the Network tier to Standard.
  5. Set the IP version to IPv4.
  6. Set the Type to Global.
  7. Click Reserve.
  8. Ensure that the Type is set to Global.
  9. Click Reserve.

gcloud

gcloud compute addresses create lb-ipv4-1 \
    --ip-version=IPV4 \
    --global

Note the IPv4 address that was reserved:

gcloud compute addresses describe lb-ipv4-1 \
    --format="get(address)" \
    --global

Setting up the load balancer backends

Console

The Cloud Console is currently unsupported for setting up header-based and parameter-based routing. Use gcloud or the API instead.

gcloud

  1. Create a health check.
        gcloud compute health-checks create http http-basic-check \
            --port 80
        
  2. Create the first backend service.
        gcloud compute backend-services create service-a \
            --global-health-checks \
            --protocol HTTP \
            --health-checks http-basic-check \
            --global
        
  3. Create the second backend service.
        gcloud compute backend-services create service-b \
            --global-health-checks \
            --protocol HTTP \
            --health-checks http-basic-check \
            --global
        
  4. Add your first instance group as the backend to the first backend service.
        gcloud compute backend-services add-backend service-a \
            --balancing-mode=UTILIZATION \
            --max-utilization=0.8 \
            --capacity-scaler=1 \
            --instance-group=first-example-ig \
            --instance-group-zone=us-east1-b \
            --global
        
  5. Add your second instance group as the backend to the second backend service.
        gcloud compute backend-services add-backend service-b \
            --balancing-mode=UTILIZATION \
            --max-utilization=0.8 \
            --capacity-scaler=1 \
            --instance-group=second-example-ig \
            --instance-group-zone=us-east1-c \
            --global
        

Creating the URL map

Console

The Cloud Console is currently unsupported for setting up header-based and parameter-based routing. Use gcloud or the API instead.

gcloud

  1. Create a YAML file /tmp/web-map-http.yaml, making sure to substitute PROJECT_ID with your project ID.

    defaultService: https://www.googleapis.com/compute/v1/projects/[project-id]/global/backendServices/service-a
    hostRules:
    - hosts:
      - '*'
      pathMatcher: path-matcher-1
    name: web-map-http
    pathMatchers:
    - defaultService: https://www.googleapis.com/compute/v1/projects/[project-id]/global/backendServices/service-a
      name: path-matcher-1
      routeRules:
        - matchRules:
            - prefixMatch: /
              queryParameterMatches:
                - name: ABTest
                  exactMatch: A
          priority: 0
          service: https://www.googleapis.com/compute/v1/projects/[project-id]/global/backendServices/service-a
        - matchRules:
            - prefixMatch: /
              queryParameterMatches:
                - name: ABTest
                  exactMatch: B
          priority: 1
          service: https://www.googleapis.com/compute/v1/projects/[project-id]/global/backendServices/service-b
    selfLink: https://www.googleapis.com/compute/v1/projects/[project-id]/global/urlMaps/web-map-http 
    
  2. Update the URL map.

    gcloud compute url-maps import web-map-http \
       --source /tmp/web-map-http.yaml \
       --global
    

Creating the target proxy and forwarding rule

Console

The Cloud Console is currently unsupported for setting up header-based and parameter-based routing. Use gcloud or the API instead.

gcloud

  1. Create a target HTTP proxy to route requests to your URL map.
        gcloud compute target-http-proxies create http-lb-proxy \
            --url-map web-map-http
        
  2. Create a global forwarding rule to route incoming requests to the proxy.
        gcloud compute forwarding-rules create http-content-rule \
            --address=lb-ipv4-1\
            --global \
            --target-http-proxy=http-lb-proxy \
            --ports=80
        

Testing

Note the IPv4 address that was reserved:

gcloud compute addresses describe lb-ipv4-1 \
    --format="get(address)" \
    --global

Test this setup by running:

curl http://[IP_ADDRESS]?ABTest=A
curl http://[IP_ADDRESS]?ABTest=B

In a browser, open http://[IP_ADDRESS]?ABTest=A and http://[IP_ADDRESS]?ABTest=B.

Setting up custom HTTP header-based routing

This example demonstrates adding and removing custom HTTP headers to do intelligent routing.

Before you begin

You can use an existing external HTTP(S) load balancer or create a new one.

You can use this feature with any of the supported backend types. This example assumes that you're using VMs in an instance group.

To set up a simple load balancer, see the query pararameter-based example above.

Updating the URL map

Console

The Cloud Console is currently unsupported for setting up header-based and parameter-based routing. Use gcloud or the API instead.

gcloud

  1. Create a YAML file /tmp/web-map-http.yaml.

    This example demonstrates using HTTP request headers to do A/B testing by matching on values in the request's HTTP headers.

    defaultService: $[DEFAULT_SERVICE_URL]
    kind: compute#urlMap
    name: web-map-http
    hostRules:
    - hosts:
      - '*'
      pathMatcher: matcher1
    pathMatchers:
    - defaultService: $[DEFAULT_SERVICE_URL]
      name: matcher1
      routeRules:
        - matchRules:
            - prefixMatch: /
              headerMatches:
                - headerName: ABTest
                  exactMatch: A
          priority: 0
          service: https://www.googleapis.com/compute/v1/projects/[project-id]/global/backendServices/service-a
        - matchRules:
            - prefixMatch: /
              headerMatches:
                - headerName: ABTest
                  exactMatch: B
          priority: 1
          service: https://www.googleapis.com/compute/v1/projects/[project-id]/global/backendServices/service-b
    
  2. Update the URL map.

    gcloud compute url-maps import web-map-http \
       --source /tmp/web-map-http.yaml \
       --global