URL maps define rules and matching patterns for URL-based routing of requests to the appropriate backend services. A default service is defined to handle any requests that do not match a specified host rule or path matching rule. In some situations, such as the cross-region load balancing example , you might not define any URI rules and rely only on the default service. For content-based routing of traffic, the URL map allows you to divide your traffic by examining the URI components to send requests to backends that are optimized for that type of traffic.

URL map properties

See the UrlMaps resource for descriptions of the properties that available when working with URL maps through either the REST API or the gcloud compute command-line tool.

Adding a URL map

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

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

To create a URL map using the API, send a POST request to the following URI:

POST https://www.googleapis.com/v1/compute/projects/<project-id>/global/urlMaps

{
  "name": NAME,
  "defaultService": BACKEND_SERVICE
}

After creating a URL map, you might next want to define the host and path rules for routing requests to backend services. See updating the URL map

Adding path matchers

A path matcher maps HTTP request paths to backend services. It requires a default backend service to send unmatched requests to, and optionally accepts path rules that route requests to backend services based on the request path.

To create a path matcher using gcloud compute , use the url-maps edit command to open the URL map file in a text editor:

$ gcloud compute url-maps edit URL_MAP

Uncomment the following lines in the file:

pathMatchers:
- defaultService: https://www.googleapis.com/compute/v1/projects/my-project/global/backendServices/www-default
  name: www
  pathRules:
  - paths:
    - /search
    - /search/*
    service: https://www.googleapis.com/compute/v1/projects/my-project/global/backendServices/search-service

Update the defaultService value to use the fully qualified URL to your default backend service for paths that don't match any of your rules. Add a paths line under pathRules for each set of paths to match to a service; in the example above, requests to /search and all paths under /search/ are sent to the backend service with name search-service .

Save and close the file to apply your changes.

If you're using the API to create your path matchers, make a POST request to the URI below, passing the path matcher properties in the request body. For example:

POST https://www.googleapis.com/compute/v1/projects/<project-id>/global/urlMaps/<url-map>/setUrlMap

{
  "pathMatchers":[{
    "name": "pathmap",
    "defaultService": "https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices/www-service",
    "pathRules": [{
      "paths": ["/videos", "/videos/*"],
      "service": "https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices/video-service"
    },{
      "paths": ["/static", "/static/*" ],
      "service": "https://www.googleapis.com/compute/v1/projects/<project-id>/global/backendServices/static-service"
    }],
}

Adding 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.

To create a host rule using gcloud compute , use the url-maps edit command to open the URL map file in a text editor:

$ gcloud compute url-maps edit URL_MAP

Uncomment the following lines in the file:

hostRules:
- hosts:
  - '*.google.com'
  - google.com
  pathMatcher: www

Update the individual hosts entries to match your domains. Each host may optionally begin with a * or *- . * acts as a glob and will match any string of atoms to the left where an atom is separated by dots (".") or dashes ("-").

Update the pathMatcher value to point to an existing path matcher name.

Save and close the file to apply your changes.

If you're using the API to create your host rules, make a POST request to the URI below, passing the path matcher properties in the request body. For example:

POST https://www.googleapis.com/compute/v1/projects/<project-id>/global/urlMaps/<url-map>/setUrlMap

{
  "urlMap": "www-map",
  "hostRules":[{
    "hosts": [ "*" ],
    "pathMatcher": "pathmap"
  }]
}

Testing URL maps

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 '<yourhost/yourpath>' to map to service
'<expected service>', but actually mapped to '<actual service>'.

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

$ gcloud compute url-maps edit <url-map>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

Here is the equivalent JSON structure in the body of an HTTP POST request to https://www.googleapis.com/compute/v1/projects/<project-id>/global/urlMaps/web-map/setUrlMap :

body = {
 ...
  "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"
    }]
}

Listing URL maps

To list URL maps using gcloud compute , use the url-maps list command:

$ gcloud compute url-maps list

In the API, send an empty GET request to the following URI:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/urlMaps

Getting a URL map

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

$ gcloud compute url-maps descibe URL_MAP

Note that the name of the url map is optional; omitting it returns verbose information about all URL maps in the project.

In the API, send an empty GET request to the following URI:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/urlMaps/<url-map>

Deleting a URL map

To delete a URL map using gcloud compute , 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]

In the API, send an empty DELETE request to:

https://www.googleapis.com/compute/v1/projects/<project-id>/global/urlMaps/<url-map>

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Last updated August 13, 2014.