This guide shows you how to configure Google Cloud URL maps. Before following this guide, familiarize yourself with URL map concepts.
URL maps are used with the following Google Cloud products:
Internal HTTP(S) Load Balancing and Traffic Director support advanced traffic management use cases. For more information, see:
- Traffic management overview for internal HTTP(S) load balancers
- Traffic management overview for Traffic Director
Configuring URL maps
You can add backend services and backend buckets to a URL map.
Backend buckets are supported with external HTTP(S) load balancers only.
Adding a URL map
Console
To add a URL map using the Cloud Console, perform the following steps:
- Go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- Select Host and path rules.
- Click Add host and path rule.
- Fill in the Host field, Paths field, or both, and select a backend service or backend bucket.
- 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_NAME \ (--default-backend-bucket=DEFAULT_BACKEND_BUCKET | --default-service=DEFAULT_SERVICE) \ [--description DESCRIPTION] \ [--global | --region=REGION]
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:
- If you're not already on the Host and path rules screen, go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- In the Host and path rules screen, either click Add host and path rule or click an existing Paths field.
- Enter the path to configure, for example,
/video
. - 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_NAME \ --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.
Adding a host rule
Console
To create a host rule using the Cloud Console, perform the following steps:
- If you're not already on the Host and path rules screen, go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- On the Host and path rules screen, either click Add host and path rule or click an existing Hosts field.
- Enter a fully-qualified Host name, for example
web.example.com
. - 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_NAME \ --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
Selecting a backend service or backend bucket
Console
To select a backend service or backend bucket for a URL map, perform the following steps:
- If you're not already on the Host and path rules screen, go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- In the Host and path rules screen, in the Backends field pull-down menu, select an available backend service or backend bucket.
- Look for the blue checkmark to the left of Host and Path Rules and click the Update button.
gcloud
To select a backend service or backend bucket 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 ...]
Validating 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. Note that you don't need to use any live services
or even existing services for the tests. You can use any example service names
to create and run the tests. This is unlike other url-maps
commands
(such as edit
, import
) where the URL map must reference pre-existing
(but not necessarily live) services.
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.
Validating 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.
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
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 calledvideo-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 newvideo-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
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'.
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
Testing 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:
- Go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- Click Host and path rules.
- Beneath the Host and path rules, click Show configuration tests.
- Click Add configuration test. Add the following test URLs and backends:
- Test URL
example.com
and Backendwww-service.
- Test URL
example.net
and Backendwww-service.
- Test URL
example.net/web
and Backendwww-service.
- Test URL
example.com/videos
and Backendvideo-service.
- Test URL
example.com/videos/browse
and Backendvideo-service.
- Test URL
example.net/static
and Backendstatic-service.
- Test URL
example.net/static/images
and Backendstatic-service.
- Test URL
- 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_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 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
You cannot list all of your URL maps in the Cloud Console.
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:
- Go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- 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_NAME
Deleting 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:
- Go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- On the Load Balancer Details screen, view the Host and path rules.
- Click the "X" to the right of a URL map to delete it. The URL map disappears.
- 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_NAME [--quiet]
Deleting a path matcher
Console
To delete a path matcher, perform the following steps:
- Go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- Select Host and path rules.
- In the Paths field for an existing URL map, click the "x" on the path matcher's name.
- 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]
Deleting a host rule
Console
To delete a host rule, perform the following steps:
- If you're not already on the Host and path rules screen, go to the Load balancing page.
- Click the Name of a load balancer.
- On the Load Balancer Details screen, click Edit for the selected load balancer.
- Select Host and path rules.
- In the Hosts field for an existing URL map, click the "x" on the host's name.
- 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
What's next
- See URL maps overview for information on how URL maps work.
- See External HTTP(S) Load Balancing overview for information on how URL maps work in external HTTP(S) Load Balancing.
- See Internal HTTP(S) Load Balancing overview for information on how URL maps work in Internal HTTP(S) Load Balancing.