URL Map Concepts

HTTP(S) Load Balancing allows you to direct traffic to different backend services or backend buckets based on the domain and path of the incoming URL. For example, you can send requests for https://example.com/video to one backend service, requests for https://example.com/audio to another backend service, and requests for https://example.com/video to a Cloud Storage backend bucket.

Before you read this, make sure that you are familiar with overall HTTP(S) Load Balancing concepts.

About URL maps

When a request comes into the load balancer, the load balancer routes the request to a particular backend service or backend bucket based on configurations in a URL map.

For example, assume you have the following setup:

  • One IP address. All requests to your organization go to the same IP address and the same load balancer. Traffic is directed to different backend services based on the request URL.
  • Two domains
    • example.net, which hosts training videos
    • example.org, which hosts your organization website
  • Four sets of servers
    • One hosts your organization website (backend service: org-site)
    • One hosts the overall training video website (backend service: video-site)
    • One hosts high definition (HD) training videos (backend service: video-hd)
    • One hosts standard definition (SD) training videos (backend service: video-sd)

You want the following to happen:

  • Requests to example.org (or any domain other than example.org) to go to the org-site backend service
  • Requests to example.net that do not match more specific paths to go to the video-site backend service
  • Requests to example.net/video/hd/* to go to the video-hd backend service
  • Requests to example.net/video/sd/* to go to the video-sd backend service
Example service setup (click to enlarge)
Example service setup (click to enlarge)

You can create a URL map that sets this up. The next section describes some of the URL map components you'll work with.

URL map components

Using host values (example.com) and path values (/path/to/file) in the request URL, the URL map forwards the request to the correct backend service or backend bucket.

Basic URL map flow (click to enlarge)
Basic URL map flow (click to enlarge)

A URL map has the following components: URL map, host rule, path matcher.

  • URL map: the URL map itself is a resource you create. Its only required parameter is a default service, which is the backend service or backend bucket the URL map directs traffic to if there are no more specific matches. The default service has a default host rule of "all hosts" (*). It matches all domains not specified in more specific host rules. You can override it by creating a specific host rule for * and pointing that host rule at a specific path matcher.
  • host rule: A host rule matches against the domain portion of the request URL. For a URL such as example.com/video/hd, the host rule matches against example.com. If the incoming domain and the domain specified in the host rule match, the URL map then processes the request with the path matcher specified in the host rule. A URL map starts with a default host rule that matches all hosts (*). If you want all hosts to use the same path matcher, you don't have to specify an explicit host rule. You can specify more than one domain in a host rule. If you want each host rule to point to a different path matcher, you can add more than one host rule to a URL map.
  • path matcher: path matchers match the path (example.com/video/hd) portion of a URL against one or more path rules, where they are matched by paths or path prefixes. You can have more than one path matcher in a URL map, but each one must be linked to a different host rule.
    • path matcher default service: If the host rule has matched, but the path does not match any of the path matcher path rules, the URL map forwards the request to the backend service or bucket specified as the path matcher default service.
    • path rules: If the path in the URL matches a path rule, the URL map forwards the request to the backend service or backend bucket specified by the rule. Rules use "longest match." If the path matcher has two rules, one matching /video/* and one matching /video/hd/*, and the URL map receives a request for /video/hd/example.mp4, the URL map sends the request to the backend service or backend bucket associated with /video/hd/*.

URL map simplest case

In the simplest case, all URLs go to the same backend service or backend bucket. In this case, the URL map does not have a path matcher. Its only setting is its default service, which handles all requests. All traffic is sent to the specified backend service and load balanced across available instances.

URL map with no rules except default (click to enlarge)
URL map with no rules except default (click to enlarge)

URL map with path matchers, path rules, and host rules

With path matchers and rules, you can create more complex matching rules that send different requests to different backend services or backend buckets based on the path in the request URL.

This section shows how traffic to the sample setup at the top of the page would be processed by a URL map.

After the URL map is configured, incoming requests are processed as follows:

  1. The load balancer target proxy forwards the request to the URL map.
  2. The URL map compares the URL domain to any host rule. If there is no match, the URL map forwards the request to the URL map default service.
  3. If the host does match, the URL map processes the request using the path matcher specified by the host rule.
  4. If the path does not match any path rule, the URL map forwards the request to the service or bucket specified in the path matcher default service.
  5. If the path does match a path rule, the URL map forwards the request to the backend service or backend bucket specified in the path rule.
URL map with a path rule, path matchers, and a host rule
         (click to enlarge)
URL map with a path rule, path matchers, and a host rule (click to enlarge)
  • All requests to the load balancer IP address that had a host name other than example.org are sent to the org-site backend service.
  • All requests to example.net that do not specify /video/hd or /video/sd are sent to the video-hd backend service.
  • All request to example.net/video/hd or example.net/video/sd are sent to the respective backend services.

This setup can be created with the following commands:

  1. Create the instance groups and backend services necessary for your configuration. See Creating Content-Based Load Balancing for a complete load balancing setup example.
  2. Create a URL map and set its default service to org-site. This backend service will receive all traffic that doesn't match a more specific host rule.
        gcloud compute url-maps create video-org-url-map \
            --default-service org-site
        
  3. Create a path matcher that sends /video/hd traffic to video-hd, /video/sd traffic to video-sd, and all other traffic that matches the host rule but doesn't match a more specific path to video-site.
        gcloud compute url-maps add-path-matcher video-org-url-map \
            --default-service video-site \
            --path-matcher-name video-matcher \
            --path-rules=/video/hd=video-hd,/video/hd/=video-hd,/video/sd=video-sd,/video/sd/=video-sd
        
  4. Create a host rule that sends all traffic for example.org to the video-matcher path matcher. All other hosts will use the URL map's default service.
        gcloud compute url-maps add-host-rule video-org-url-map \
            --hosts example.net --path-matcher-name video-matcher
        

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Load Balancing