Use URL maps

This guide shows you how to configure Google Cloud URL maps. A URL map is a set of rules for routing incoming requests. A minimal URL map matches all incoming request paths (/*).

Before following this guide, familiarize yourself with URL map concepts.

URL maps are used with the following Google Cloud products:

URL maps used with global external HTTP(S) load balancers, regional external HTTP(S) load balancers, internal HTTP(S) load balancers, and Traffic Director also support several advanced traffic management features. For more information, see URL map concepts: Advanced traffic management.

URL map defaults

URL maps have two defaults, as described in the following table.

Default type Setting Meaning
URL map default gcloud compute url-maps create

--default-service | --default-backend-bucket

The specified default backend service or backend bucket is used if none of the path matchers or host rules match the incoming URL.
Path matcher default gcloud compute url-maps add-path-matcher

--default-service | --default-backend-bucket

The specified default backend service or backend bucket is used if the URL's path matches a path matcher, but none of the specified --path-rules match.

Host rules

A host rule defines a set of hosts to match requests against.

In a host rule, the hostname must be a fully qualified domain name (FQDN). The hostname can't be an IPv4 or IPv6 address. For example:

  • Works: example.com
  • Works: web.example.com
  • Works: *.example.com
  • Doesn't work: 35.244.221.250

Configure URL maps

A URL map can send traffic to backend services or backend buckets. Backend buckets are not supported with regional external HTTP(S) load balancers and internal HTTP(S) load balancers.

Console

To add a URL map using the Cloud console, perform the following steps:

  1. Go to the Load balancing page.

    Go to the Load balancing page

  2. Click the Name of a load balancer.
  3. On the Load Balancer Details screen, click Edit for the selected load balancer.
  4. Select Host and path rules.
  5. Click Add host and path rule.
  6. Fill in the Host field, Paths field, or both, and select a backend service or backend bucket.
    1. Enter a fully qualified Host name, for example web.example.com.
    2. Enter the path—for example, /video.
    3. In the Host and path rules screen, in the Backends menu, select an available backend service or backend bucket.
  7. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

To add a URL map using the Google Cloud CLI, use the url-maps create command:

gcloud compute url-maps create URL_MAP_NAME \
   (--default-backend-bucket=DEFAULT_BACKEND_BUCKET | --default-service=DEFAULT_SERVICE) \
   [--description DESCRIPTION] \
   [--global | --region=REGION]

For regional external HTTP(S) load balancers and internal HTTP(S) load balancers, make sure to include the --region flag when you create the URL map.

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

gcloud compute url-maps add-path-matcher URL_MAP_NAME \
   (--default-backend-bucket=DEFAULT_BACKEND_BUCKET | --default-service=DEFAULT_SERVICE) \
   --path-matcher-name PATH_MATCHER \
   [--path-rules="PATH=SERVICE or BUCKET"]

This command requires a default backend service or backend bucket to which it can send unmatched requests. The --path-rules flag defines mappings between request paths and backend services or buckets. The following example routes the request paths /video/ and /video/* to the video-service backend service:

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

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

gcloud compute url-maps add-host-rule URL_MAP_NAME \
    --hosts=[HOSTS] --path-matcher-name=PATH_MATCHER

For example, the following --hosts value matches requests against www.example.com and any subdomain of google.com:

--hosts=[*.google.com,www.example.com]

To change the default service or default bucket of a URL map, use the url-maps set-default-service command.

gcloud compute url-maps set-default-service URL_MAP_NAME
  (--default-backend-bucket=DEFAULT_BACKEND_BUCKET
  | --default-service=DEFAULT_SERVICE)[GCLOUD_WIDE_FLAG ...]

Validate the URL map configuration

Before deploying a URL map, make sure you validate the URL map configuration to ensure that the map is routing requests to the appropriate backends as intended. You can do this by adding tests to the URL map configuration. You can experiment with different URL map rules and run as many tests as needed to be confident that the map will route traffic appropriately when it is deployed. Additionally, if any rule changes are needed in the future, you can test those changes before actually going live with the new configuration.

Use the gcloud compute url-maps validate command to validate URL map configuration. Note that this command only tests the configuration provided. Irrespective of whether the tests pass or fail, no changes are saved to the URL map that is currently deployed. This is unlike other url-maps commands (edit, import) that also run the same tests but will actually save the new configuration if tests pass. Use the validate command when you want to test new routing configuration without making changes to the currently deployed URL map.

The validate command allows you to test advanced route configurations such as routing based on headers and query parameters, HTTP to HTTPS redirects, and URL rewrites.

Console

You cannot use the Cloud console to validate URL map configuration. Use gcloud or the REST API instead.

gcloud

To validate your URL map configuration use the gcloud compute url-maps validate command:

gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE
  • PATH_TO_URL_MAP_CONFIG_FILE: Replace with a path to the file that contains the URL map configuration for validation.

Validate changes to an existing load balancer's URL map

If you have an existing load balancer that needs changes to the URL map, you can test those configuration changes before making them live.

  1. Export the load balancer's existing URL map to a YAML file.

    gcloud compute url-maps export URL_MAP_NAME \
       --destination PATH_TO_URL_MAP_CONFIG_FILE \
       --global
    
  2. Edit the YAML file with new configuration. For example, if you want to edit an external HTTP(S) load balancer and send all requests with the path /video to a new backend service called video-backend-service, you can add tests to the URL map configuration as follows:

    Existing URL map configuration with a single default web-backend-service:

     kind: compute#urlMap
     name: URL_MAP_NAME
     defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
     

    Edited URL map configuration with added path matcher and tests for both the default web-backend-service and the new video-backend-service backend service:

     kind: compute#urlMap
     name: URL_MAP_NAME
     defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
     hostRules:
     - hosts:
       - '*'
       pathMatcher: pathmap
     pathMatchers:
     - defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
       name: pathmap
       pathRules:
       - paths:
         - /video
         - /video/*
         service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/video-backend-service
     tests:
     - description: Test routing to existing web service
       host: foobar
       path: /
       service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/web-backend-service
     - description: Test routing to new video service
       host: foobar
       path: /video
       service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendService/video-backend-service
    
  3. Validate the new configuration.

    gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE
    

    If all tests pass successfully, you should see a success message such as:

    Successfully validated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/URL_MAP_CONFIG_FILE_NAME
    

    If the tests fail, an error message appears. Make the required fixes to the URL map config file and try validating again.

    Error: Invalid value for field 'urlMap.tests': ''.
    Test failure: Expect URL 'HOST/PATH' to map to service 'EXPECTED_BACKEND_SERVICE', but actually mapped to 'ACTUAL_BACKEND_SERVICE'.
    
  4. Once you know that the new configuration works and does not impact your existing setup, you can import it into the URL map. Note that this step will also deploy the url map with the new configuration.

    gcloud compute url-maps import URL_MAP_NAME \
       --source PATH_TO_URL_MAP_CONFIG_FILE \
       --global
    

Test a URL map

You can add configuration tests to a URL map to ensure that your URL map routes requests to the backend services or backend buckets as intended.

When you edit your URL map, the tests run, and an error message appears if a test fails:

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

Adding tests to URL maps is optional.

Console

To run tests from the Cloud console:

  1. Go to the Load balancing page.

    Go to the Load balancing page

  2. Click the Name of a load balancer.
  3. On the Load Balancer Details screen, click Edit for the selected load balancer.
  4. Click Host and path rules.
  5. Beneath the Host and path rules, click Show configuration tests.
  6. Click Add configuration test. Add the following test URLs and backends:
    • Test URL example.com and Backend www-service.
    • Test URL example.net and Backend www-service.
    • Test URL example.net/web and Backend www-service.
    • Test URL example.com/videos and Backend video-service.
    • Test URL example.com/videos/browse and Backend video-service.
    • Test URL example.net/static and Backend static-service.
    • Test URL example.net/static/images and Backend static-service.
  7. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

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

gcloud compute url-maps edit URL_MAP_NAME

This launches a text editor. For external HTTP(S) load balancers, your tests must use the following format:

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

For regional external HTTP(S) load balancers and internal HTTP(S) load balancers, your service URLs must point to regional backend services. For example:

https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/backendServices//www-service

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

List URL maps

Console

You cannot list all of your URL maps in the Cloud console.

gcloud

To display a list of URL maps using the Google Cloud CLI, use the url-maps list command.

gcloud compute url-maps list

Get information about a URL map

Console

To get information about a URL map, perform the following steps:

  1. Go to the Load balancing page.

    Go to the Load balancing page

  2. Click the Name of a load balancer.
  3. On the Load Balancer Details screen, click Edit for the selected load balancer.
  4. View the Host and path rules.

gcloud

To get information about a single URL map using the Google Cloud CLI, use the url-maps describe command.

gcloud compute url-maps describe URL_MAP_NAME

Delete a URL map

You can delete a URL map only after you've deleted all target proxies that reference it. For more information, see Deleting a target proxy.

Console

To delete a URL map, perform the following steps:

  1. Go to the Load balancing page.

    Go to the Load balancing page

  2. Click the Name of a load balancer.
  3. On the Load Balancer Details screen, click Edit for the selected load balancer.
  4. On the Load Balancer Details screen, view the Host and path rules.
  5. Click the "X" to the right of a URL map to delete it. The URL map disappears.
  6. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

To delete a URL map using the Google Cloud CLI, 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_NAME [--quiet]

Delete a path matcher

Console

To delete a path matcher, perform the following steps:

  1. Go to the Load balancing page.

    Go to the Load balancing page

  2. Click the Name of a load balancer.
  3. On the Load Balancer Details screen, click Edit for the selected load balancer.
  4. Select Host and path rules.
  5. In the Paths field for an existing URL map, click the "x" on the path matcher's name.
  6. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

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

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

Delete a host rule

Console

To delete a host rule, perform the following steps:

  1. If you're not already on the Host and path rules screen, go to the Load balancing page.

    Go to the Load balancing page

  2. Click the Name of a load balancer.
  3. On the Load Balancer Details screen, click Edit for the selected load balancer.
  4. Select Host and path rules.
  5. In the Hosts field for an existing URL map, click the "x" on the host's name.
  6. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

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 URL_MAP_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

Traffic management guides

Not all URL map features are available for all products. URL maps are used with load balancers to support several advanced traffic management features, not all of which are supported on the global external HTTP(S) load balancer (classic).

Use the following table to learn about the URL map features for management works.

Product URL map features and traffic management guides
Global external HTTP(S) load balancer Load balancer features: Routing and traffic management

Traffic management overview

Setting up traffic management

Setting up a URL redirect

Setting up an HTTP-to-HTTPS redirect

Global external HTTP(S) load balancer (classic) Load balancer features: Routing and traffic management

Traffic management overview

Setting up a URL redirect

Setting up an HTTP-to-HTTPS redirect

Regional external HTTP(S) load balancer Load balancer features: Routing and traffic management

Traffic management overview

Setting up traffic management

Setting up a URL redirect

Setting up an HTTP-to-HTTPS redirect

Internal HTTP(S) load balancer Load balancer features: Routing and traffic management

Traffic management overview

Setting up traffic management

Setting up URL redirects

Setting up HTTP-to_HTTPS redirects

Traffic Director Traffic Director features: Routing and traffic management

Advanced traffic management overview

Configuring advanced traffic management

API and gcloud CLI reference

In addition to the Cloud console, you can use the API and gcloud CLI to create URL maps.

API

For descriptions of the properties and methods available to you when working with URL maps through the REST API, see the following:

Product API documentation
External HTTP(S) Load Balancing urlMaps
Internal HTTP(S) Load Balancing regionUrlMaps
Traffic Director urlMaps

gcloud CLI

For the Google Cloud CLI in the Google Cloud CLI, see the following:

For advanced traffic management, use YAML files and import them with the gcloud compute url-maps import command.

What's next