Google Cloud HTTP(S) load balancers and Traffic Director use a URL map to direct requests to a destination. When you configure an HTTP(S) load balancer or Traffic Director, you create a URL map. This URL map directs traffic to one or more of the following destinations based on rules that you define:
- Default backend service
- Non-default backend service
- Default backend bucket
- Non-default backend bucket
A backend service represents a collection of backends, which are instances of an application or microservice. A backend bucket is a Google Cloud Storage bucket, which is commonly used to host static content, such as images.
For example, you can use a single URL map to route requests based on the request host and path:
- Requests for
https://example.com/video
go to one backend service. - Requests for
https://example.com/audio
go to a different backend service. - Requests for
https://example.com/images
go to a Cloud Storage backend bucket. - Requests for any other host and path combination go to a default backend service.
URL maps are used with the following Google Cloud products:
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 that 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
hosts training videos.example.org
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
).
- One hosts your organization website (backend service:
You want the following to happen:
- Requests to
example.org
(or any domain other thanexample.net
) to go to theorg-site
backend service. - Requests to
example.net
that do not match more specific paths to go to thevideo-site
backend service. - Requests to
example.net/video/hd/*
to go to thevideo-hd
backend service. - Requests to
example.net/video/sd/*
to go to thevideo-sd
backend service.
The URL map lets you set up this type of host and path-based routing.
Advanced traffic management
Internal HTTP(S) Load Balancing and Traffic Director use URL maps for host and path-based routing (as described in this document). When used with these products, URL maps also support advanced traffic management features. For more information about advanced traffic management, see the Traffic management overview and Advanced traffic management.
Naming
Each URL map has a name. When you create an HTTP(S)-based load balancer by using
the Google Cloud Console, the URL map is assigned a name. This name is the same as
the name of the load balancer. If you use gcloud
or the API, you can define a
custom name for the URL map.
URL map components
A URL map is a Google Cloud 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:
- 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
isexample.net
. - A path is the portion of a URL following the host name and optional port
number; for example, the path portion of the URL
http://example.net/video/hd
is/video/hd
.
This diagram shows the structure of the load balancing configuration objects in relation to each other.
You control which backend services or backend buckets receive incoming requests by using the following URL map configuration parameters:
Default backend 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 backend bucket to which Google Cloud directs 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 nameexample.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 URLshttp://example.org
,http://example.net/video/hd
, andhttp://example.com/audio
, all three host namesexample.org
,example.net
, andexample.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 namesfoo.example.net
andbar.example.net
.- Port number. You can also use the Host rule parameter to specify a
port number. For example, to direct
example.net
requests for port 8080, set the host rule toexample.net:8080
.
- Port number. You can also use the Host rule parameter to specify a
port number. For example, to direct
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 backend 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 backend bucket to which Google Cloud directs 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 contains more information about how path rules work.
Order of operations
For a given host name and path in a requested URL, Google Cloud 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, Google Cloud 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, 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, Google Cloud 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 Google Cloud 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, Google Cloud 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 do 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 a limited set of path rules. For more complex cases, you need to do path-based regular expression matching on your backends.
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 multiple host rules can reference a single path matcher. Consequently, each unique URL is directed to only one backend service or backend bucket:
Google Cloud 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. Backend services can have backend instance groups or backend network endpoint groups (NEGs) 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 both a target HTTP proxy and a target HTTPS proxy reference the URL map.
You can use a URL map to configure redirection, as shown in the following guides:
- Setting up HTTP-to-HTTPS redirect for external HTTP(S) load balancers
- Setting up traffic management for internal HTTP(S) load balancers
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. Either the default backend service or the default backend bucket (whichever one you defined) handles all requested URLs.
If you define a default backend service, Google Cloud directs requests to its backend instance groups or backend NEGs according to the backend service's configuration.
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 an external HTTP(S) load balancer. For an example of how to create the external HTTP(S) load balancer's other components, see Creating an external HTTP(S) load balancer. For an example of how to create an internal HTTP(S) load balancer's URL map and other components, see Preparing for Internal HTTP(S) Load Balancing setup.
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 namedorg-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 namedvideo-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 namedvideo-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
- The default backend service is
Create a host rule for the
example.net
host name that references thevideo-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.
The following table explains the request processing shown in the preceding diagram.
Host name | URL paths | Selected backend service | Reason for selection |
---|---|---|---|
Host name example.org and all other host names
different fromexample.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. |
API and gcloud reference
For descriptions of the properties and methods available to you when working with URL maps through the REST API, see the following:
- Global: urlMaps
- Regional: regionUrlMaps
For the gcloud
command-line tool, see the following:
- gcloud compute url-maps
- Global:
--global
- Regional:
--region=[REGION]
- Global:
What's next
- To add, test, list, or delete a URL map, see Using URL maps.
- For information routing rule maps with Traffic Director, see Cloud Load Balancing routing rule maps overview.