URL Map Concepts

Google Cloud Platform HTTP(S)-based load balancers use a URL map to direct incoming requests to backend services and (for external HTTP(S) load balancers only) backend buckets.

Every HTTP(S)-based load balancer you create must have a URL map. When you create an HTTP(S)-based load balancer using the GCP Console, the name of the load balancer and its URL map are the same. Each URL map directs traffic to a default backend service or default backend bucket. In addition to this default, you can direct traffic to different backend services and backend buckets based on the requested host name and path portion of a URL.

For example, you can route requests for https://example.com/video to one backend service, requests for https://example.com/audio to a different backend service, and requests for https://example.com/images to a Cloud Storage backend bucket, all in a single URL map and HTTP(S) load balancer.

Before you read this, make sure that you are familiar with overall HTTP(S) load balancing concepts:

This document describes how URL maps work with HTTPS(S) load balancers. Traffic Director, GCP's fully-managed traffic control plane for service meshes, uses URL maps and supports additional configuration parameters. Refer to the Traffic Director documentation for more information about these parameters.

About URL maps

When a request arrives at 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)

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

A URL map is a GCP configuration resource that directs requests for URLs to backend services or backend buckets. It does so by using the host name and path portions for each URL it processes:

host name: A host name is the domain name portion of a URL; for example, the host name portion of the URL http://example.net/video/hd is example.net.
path: The path is the portion of a URL following the host name; for example, the path portion of the URL http://example.net/video/hd is /video/hd.

You control which backend services or backend buckets receive incoming requests by using the following URL map configuration parameters:

Default service or default backend bucket: When you create a URL map, you must specify either a default backend service or a default backend bucket, but not both. This default represents the backend service or bucket to which GCP will direct requests for URLs with any host name, unless there is an applicable host rule.
Host rule: A host rule directs requests sent to one or more associated host names to a single path matcher. The host name portion of a URL is exactly matched against the set of the host rule's configured host names. To direct requests for http://example.net/video/hd to a path matcher, you need a single host rule that at least includes the host name example.net. That same host rule could also handle requests for other host names, but it would direct them to the same path matcher. If you need to direct requests to different path matchers, you must use different host rules. Two host rules in a URL map can't include the same host name. It is possible to match all host names by specifying the wildcard character * in the host rule. For example, for the URLs http://example.org, http://example.net/video/hd and http://example.com/audio, all three host names example.org, example.net and example.com can be matched by specifying * in the host rule. It is also possible to match a partial host name by wildcard character *. For example, a host rule *.example.net is matched against both host names foo.example.net and bar.example.net.
Path matcher: A path matcher is the configuration parameter referenced by a host rule. It defines the relationship between the path portion of a URL and the backend service or backend bucket that should serve the request. A path matcher consists of two elements:
- Path matcher default service or path matcher default backend bucket: For each path matcher, you must at least specify a default backend service or default backend bucket, but not both. This default represents the backend service or bucket to which GCP will direct requests for URLs whose host names match a host rule associated with the path matcher and whose URL paths do not match any path rule in the path matcher.
- Path rules: For each path matcher, you can specify one or more path rules, which are key-value pairs mapping a URL path to a single backend service or backend bucket. The next section, Order of operations, contains more information about how path rules work.

Order of operations

For a given host name and path in a requested URL, GCP uses the following procedure to direct the request to the correct backend service or backend bucket, as configured in your URL map:

If the URL map does not contain a host rule for the URL's host name, then GCP directs requests to the URL map's default backend service or default backend bucket, depending on which one you defined.
If the URL map contains a host rule that includes the URL's host name, then the path matcher referenced by that host rule is consulted:
- If the path matcher contains a path rule that exactly matches the URL's path, then GCP directs requests to the backend service or backend bucket for that path rule.
- If the path matcher does not contain a path rule that exactly matches the URL's path, but does contain a path rule ending in /* whose prefix matches the longest section of the URL's path, then GCP directs requests to the backend service or backend bucket for that path rule. For example, for the URL map containing two path matcher rules /video/hd/movie1 and /video/hd/* if the URL contains the exact path /video/hd/movie1, it is matched against that path rule.
- If neither of the previous conditions is true, then GCP directs requests to the path matcher's default backend service or default backend bucket, depending on which one you defined.

Path matcher constraints

Path matchers and path rules have the following constraints:

A path rule can only include a wildcard character (*) after a forward slash character (/). For example, /videos/* and /videos/hd/* are valid for path rules, but /videos* and /videos/hd* are not.
Path rules do not use regular expression or substring matching. For example, path rules for either /videos/hd or /videos/hd/* do not apply to a URL with the path /video/hd-abcd. However, a path rule for /video/* does apply to that path.
Path matchers (and URL maps in general) do not offer features that function like Apache LocationMatch directives. If you have an application that generates dynamic URL paths that have a common prefix, such as /videos/hd-abcd and /videos/hd-pqrs, and you need to send requests made to those paths to different backend services, you might not be able to accomplish that with a URL map. For simple cases containing only a few possible dynamic URLs, you might be able to create a path matcher with the limited set of path rules. For more complex cases, you will need to do path based regular expression matching on your backend VMs.

A host name can only reference a single host rule, and a host rule can only reference a single path matcher. However, a single host rule can process multiple host names, and a single path matcher can be referenced by multiple host rules. Consequently, each unique URL is directed to only one backend service or backend bucket:

GCP uses the host name portion of a URL to select a single host rule and its referenced path matcher.
In the path matcher, you cannot create more than one path rule for the same path. For example, requests for /videos/hd cannot be directed to more than one backend service or backend bucket. Note that backend services can have backend instance groups or backend network endpoint groups in different zones and regions, and you can create backend buckets that use multi-regional storage classes.

URL maps and protocols

You can use the same URL map, host rules, and path matchers to process both HTTP and HTTPs requests submitted by clients, as long as the URL map is referenced by both a target HTTP proxy and a target HTTPS proxy.

URL maps do not provide protocol redirection for connections between clients and the load balancer. For example, you cannot use a URL map to instruct client systems to switch from HTTP to HTTPS. You must implement all client protocol redirection on your backend VMs.

Simplest URL map

The simplest URL map only has a default backend service or a default backend bucket. It contains no host rules and no path matchers. All requested URLs are handled by either the default backend service or default backend bucket, whichever one you defined.

If you define a default backend service, GCP directs requests to its backend instance groups or backend network endpoint groups according to the backend service's configuration.

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

URL map example

The following example illustrates the order of operations for a URL map. For conceptual simplicity, it only uses backend services; however, you can substitute backend buckets instead.

The following steps configure the URL map for a GCP HTTP(S) load balancer. Refer to Creating Content-Based, Cross-Region Load Balancing for an example of how to create the HTTP(S) load balancer's other components. Refer to Setting Up Internal HTTP(S) Load Balancing for an example of how to create an Internal HTTP(S) load balancer's URL map and other components.

Every backend service discussed in the following example has a scheme of external and uses the HTTP, HTTPS, or HTTP/2 protocol.

Create a URL map for the load balancer and specify a default backend service. This example creates a URL map named video-org-url-map that references an existing backend service named org-site.
```
gcloud compute url-maps create video-org-url-map \
    --default-service=org-site
```
Create a path matcher named video-matcher with the following characteristics:
- The default backend service is video-site, an existing backend service.
- Add path rules that direct requests for the exact URL path /video/hd or the URL path prefix /video/hd/* to an existing backend service named video-hd.
- Add path rules that direct requests for the exact URL path /video/sd or the URL path prefix /video/sd/* to an existing backend service named video-sd.
```
gcloud compute url-maps add-path-matcher video-org-url-map \
    --path-matcher-name=video-matcher \
    --default-service=video-site \
    --path-rules=/video/hd=video-hd,/video/hd/*=video-hd,/video/sd=video-sd,/video/sd/*=video-sd
```

Create a host rule for the example.net host name that references the video-matcher path matcher.

gcloud compute url-maps add-host-rule video-org-url-map \
    --hosts=example.net \
    --path-matcher-name=video-matcher

The video-org-url-map URL map directs requested URLs to backends in the following way:

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)

GCP processes requests for URLs according to the table below:

Host name	URL paths	Selected backend service	Reason for selection
Host name `example.org` and all other host names different from `example.net`	all paths	org-site	The host name is not in any host rule of the URL map, so the request is directed to the URL map's default backend service.
Host name: `example.net`	`/video` `/video/examples`	video-site	The request goes to the default backend service because there is no path rule for `/video/` or `/video/*`. The host rule for `example.net` references a path matcher, but that path matcher does not have any path rules that would apply to these paths.
Host name: `example.net`	`/video/hd` `/video/hd/movie1` `/video/hd/movies/movie2` Other URLs that begin with `/video/hd/*`	video-hd	A host rule for `example.net` references a path matcher whose path rules direct requests for URL paths that either exactly match `/video/hd` or that begin with `/video/hd/*` to the video-hd backend service.
Host name: `example.net`	`/video/sd` `/video/sd/show1` `/video/sd/shows/show2` Other URLs that begin with `/video/sd/*`	video-sd	A host rule for `example.net` references a path matcher whose path rules direct requests for URL paths that either exactly match `/video/sd` or that begin with `/video/sd/*` to the video-sd backend service.

** Additional notes

Some URL map features described in the Traffic Director documentation and the Internal HTTP(S) Load Balancing documentation are not available to the other types of load balancers.

What's next

See Using URL Maps for information on configuring URL maps.
See HTTP(S) Load Balancing Concepts for information on how URL maps work in HTTP(S) Load Balancing.
See Internal HTTP(S) Load Balancing Concepts for information on how URL maps work in Internal HTTP(S) Load Balancing.