URL Maps

Compute Engine HTTP(S) Load Balancing allows you to direct traffic to different instances based on the incoming URL. For example, you can send requests for http://www.example.com/audio to one backend service, which contains instances configured to deliver audio files, and requests for http://www.example.com/video to another backend service, which contains instances configured to deliver video files.

About URL maps

When a request comes into the load balancer, it is routed to backend services based on configurations in a URL map. Using host values (example.com) and path values (/path) in the destination URL, the URL map forwards the request to the correct backend service.

Basic URL map flow
Basic URL map flow

URL map simplest case

In the simplest case, there is no content-based load balancing and all traffic is directed to the same groups of instances. In this case, the URL map's only setting is its default service (/*), which handles all requests that do not match another rule. This /* path matcher is created automatically by the system. Since there are no other rules, all traffic is sent to that backend service and load balanced across available instances.

URL map with no rules except default
URL map with no rules except default

URL map with path matchers and path rules

With path matchers and rules, you can create more complex matching rules that send different requests to different groups of instances based on the path in the request URL.

For example, assume you have high definition (HD) videos hosted on one set of servers, standard definition (SD) videos hosted on another set, and a general video landing site hosted on a third set. You also have a default set of servers to handle non-video-related requests to the server.

Lastly, assume you have only one domain, or that all domains pointed to the load balancer will use the same backend services.

The URL map has the following configuration:

  • No host rule, which means that requests for all hosts will use the same path matcher.
  • A path matcher that matches paths that start with /video.
  • A default path matcher (/*), which is created automatically. Tis path matcher sends any traffic that doesn't match another path matcher to the default service.
  • A path rule for the /video path matcher that matches the directory /video/hd and another rule that matches any file or directory under /video/hd (/video/hd/*). Requests that match these path rules are sent to instances in the video-hd backend service.
  • Other path rules with similar matching for /video/sd and that send the traffic to the video-sd backend service.
  • A default service for the path matcher for any requests that match the path matcher string, but not any of the path rules. In this case, a request for /video/index.html would match the path matcher, but not any of the path rules. Such requests are sent to the default backend service for the path matcher, in this case video.
  • A default service for the URL map itself, which handles all requests that don't match any path matcher. So, requests for example.com or example.net/images could be sent to the www backend service.
URL map with path rules and matchers, but no host rules
URL map with path rules and matchers, but no host rules

URL map with host rule

If you have multiple host names assigned to the same load-balanced IP address, you may direct requests based on the host name. For example, you might want to direct example.com requests to one set of path matchers and backends, but want to send requests for all other hosts to your default backend.

This diagram shows only a simple path matcher arrangement, but each host rule can have as sophisticated a path matcher and path rule arrangement as needed.

URL map with host rules
URL map with host rules

Configuring URL maps

See the UrlMaps resource for descriptions of the properties available when working with URL maps through the Cloud Platform Console, the gcloud command-line tool, or the REST API.

Adding a URL map

To add a URL map using the gcloud command-line tool, use the url-maps create command:

gcloud compute url-maps create URL_MAP \
    --default-service BACKEND_SERVICE \
    [--description DESCRIPTION]

A newly created URL map matches only one path, the default one (/*). This default path matcher is created automatically. All traffic that does not match a manually created path matcher or host rule is sent to the URL map default backend service.

Adding path matchers

A path matcher maps HTTP(S) request paths (/video) to backend services. All traffic that matches the specified path is processed by path rules in the path matcher. If a path matches a path rule, then the request is forwarded to the backends associated with that path rule. If a request matches the path matcher no path rules, then the request is forwarded to the default backend for the path matcher.

To create a path matcher using the gcloud command-line tool, use the gcloud compute url-maps add-path-matcher command:

gcloud compute url-maps add-path-matcher URL_MAP \
    --default-service BACKEND_SERVICE \
    --path-matcher-name PATH_MATCHER \
    [--path-rules PATH=SERVICE]

This command requires a default backend service to which it can send unmatched requests. Optionally, you can use the --path-rules flag to define mappings between request paths and backend services. The following example routes the request paths /video/ and /video/* to the video-service backend service:

--path-rules /video=video-service,/video/*=video-service

Both the url-maps create and url-maps add-path-matcher commands have a --default-service parameter. In create, the default service is the one used if none of the path matchers match the incoming URL. In add-path-matcher, the default service is the one used if the path matches the path matcher, but none of the --path-rules match.

Delete a path matcher

To delete a path matcher, use the gcloud compute url-maps remove-path-matcher command:

 gcloud compute url-maps remove-path-matcher URL_MAP \
     [--path-matcher-name PATH_MATCHER]

Add host rules

Once you've created one or more path matchers, you can define a host rule that sends traffic to a particular path matcher based on the host component of the request. If you do not specify a host rule, all hosts are sent to all path matchers.

If you do specify a host rule in a URL map, then the URL map matches the host rule first. If the host rule matches, then the path matcher is evaluated. If the host rule does not match, then the traffic is sent to the default backend service for the URL map and no path matchers are consulted.

If you create one host rule for * and another for a specific host like example.com, then a request for example.com will match that host rule and all other hosts will match the * rule.

To create a host rule using the gcloud command-line tool, use the gcloud compute url-maps add-host-rule command:

gcloud compute url-maps add-host-rule URL_MAP \
    --hosts HOSTS --path-matcher-name PATH_MATCHER

The flag --hosts defines a set of hosts to match requests against. For example, the following --hosts value would match requests against www.example.com and any subdomain of google.com:

--hosts *.google.com,www.example.com

Delete a host rule

To delete a host rule from your URL map, use the gcloud compute url-maps remove-host-rule command:

gcloud compute url-maps remove-host-rule NAME --host HOST

For example, to remove a host rule that contains the host google.com from a URL map named my-map, you would run the following command:

gcloud compute url-maps remove-host-rule my-map --host google.com

Test a URL map

If you're managing a large number of URL maps, it is a good idea to add tests to your URL map file to verify that your rules behave as you expect. Host and path rules can contain wildcards and can potentially overlap. The tests are like unit tests, that ensure that a request to a specific URL is directed to the correct backend service.

When you edit your URL map the tests are run immediately, and all map rules are checked. If any of the tests fail, you will see an error like the following:

Error: Invalid value for field 'urlMap.tests': ''.  Test failure: Expect URL '' to map to service
'', but actually mapped to ''.

To add tests to your URL map using the gcloud command-line tool, use the gcloud compute url-maps edit command:

gcloud compute url-maps edit URL_MAP

This launches a text editor. Your tests must use the following format:

tests:
  - host: myhost.com
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/www-service
  - host: anotherhost.net
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/www-service
  - host: anotherhost.net
    path: /web
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/www-service
  - host: myhost.com
    path: /videos
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-service
  - host: myhost.com
    path: /videos/browse
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-service
  - host: anotherhost.net
    path: /static
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/static-service
  - host: anotherhost.net
    path: /static/images
    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/static-service

Note that if you do not specify a host in a host rule, then URLs from all hosts (both myhost.com and anotherhost.net) can match. If you do have host rules, then you must create rules that match both myhost.com and anotherhost.net.

List URL maps

gcloud compute url-maps list

Get a URL map

To get information about a single URL map using the gcloud command-line tool, use the url-maps get command:

gcloud compute url-maps describe URL_MAP

Delete a URL map

To delete a URL map using the gcloud command-line tool, use the url-maps delete command. Before you can delete a URL map, any target HTTP proxies that reference the URL map must first be deleted.

gcloud compute url-maps delete URL_MAP [--quiet]

Send feedback about...

Compute Engine Documentation