Using URL Maps

HTTP(S)-based load balancers allow 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.

Configuring URL maps

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

Adding a URL map

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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil 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.
  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 gcloud command-line tool, use the url-maps create command:

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

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

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 a path matcher

A path matcher maps HTTP(S) request paths or path prefixes (for example, /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.

Console

To create a path matcher using the Cloud Console, 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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil for the selected load balancer.
  4. In the Host and path rules screen, either click Add host and path rule or click an existing Paths field.
  5. Enter the path to configure, for example, /video.
  6. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

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.

Deleting 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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil 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 \
     [--path-matcher-name PATH_MATCHER]

Adding a host rule

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

If you do not specify a host rule, then URLs from all hosts, (for example, from both example.com and example.net), can match a path.

If you do create individual host rules, (for example, a rule for example.com and another rule for example.net), then you must create path rules for both example.com and example.net.

Console

To create a host rule using the Cloud Console, 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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil for the selected load balancer.
  4. On the Host and path rules screen, either click Add host and path rule or click an existing Hosts field.
  5. Enter a fully-qualified Host name, for example web.example.com.
  6. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

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

Deleting 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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil 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 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

Selecting a backend service

Console

To select a backend service for a URL map, 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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil for the selected load balancer.
  4. In the Host and path rules screen, in the Backends field pull-down menu, select an available backend service.
  5. Look for the blue checkmark to the left of Host and Path Rules and click the Update button.

gcloud

To select a backend service using the gcloud command-line tool, 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 ...]

Testing a URL map

If you're managing a large number of URL maps, it is a good idea to add tests to each URL map file to verify that the host and path rules behave as expected. The Host and path rules can contain wildcards and can potentially overlap. The tests are like unit tests. They 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, the creation of the load balancer is blocked and you will see an error like the following. Error messages are displayed for both the console tests and the gcloud command line tests:

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

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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil 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 gcloud command-line tool, use the gcloud compute url-maps edit command:

  gcloud compute url-maps edit URL_MAP

This launches a text editor. For 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 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.

Listing URL maps

Console

In the console, you can only view URL maps for a single load balancer at a time.

  1. Go to the Load balancing page.

    Go to the Load balancing page

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

gcloud

To display a list of URL maps using the gcloud command-line tool, use the url-maps list command.

gcloud compute url-maps list

Getting 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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil for the selected load balancer.
  4. View the Host and path rules.

gcloud

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

gcloud compute url-maps describe URL_MAP

Deleting a URL map

Before you can delete a URL map, any target HTTP(S) proxies that reference the URL map must first be deleted. See Using Target Proxies for information on deleting target proxies.

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 on the Name of a load balancer.
  3. On the Load Balancer Details screen, click the Edit pencil 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 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]

Working with Cloud CDN caches

The Cloud CDN supports invalidation of specified URL map objects in Cloud CDN caches.

For more information, consult the Cloud CDN Cache Invalidation page.

What's next

Czy ta strona była pomocna? Podziel się z nami swoją opinią:

Wyślij opinię na temat...

Ta strona
Opinia na temat dokumentacji
Load Balancing
Opinia na temat usług