Use URL maps

Console

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

1. Go to the Load balancing page.

   Go to Load balancing

2. Click the Name of a load balancer.
3. On the Load Balancer Details page, click editEdit 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. On the Host and path rules page, 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 Application Load Balancers and internal Application 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 altostrat.com:

--hosts=[*.altostrat.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 ...]

Terraform

To create a global URL map, use the google_compute_url_map resource.

# url map
resource "google_compute_url_map" "default" {
  name            = "http-lb"
  default_service = google_compute_backend_bucket.default.id
}

To create a regional URL map, use the google_compute_region_url_map resource.

resource "google_compute_region_url_map" "default" {
  name            = "regional-l7-xlb-map"
  region          = "us-west1"
  default_service = google_compute_region_backend_service.default.id
}

Console

You cannot use the Google 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.

For the global external Application Load Balancer:

gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE \
    --load-balancing-scheme=EXTERNAL_MANAGED \
    --global

For the classic Application Load Balancer:

gcloud compute url-maps validate --source PATH_TO_URL_MAP_CONFIG_FILE \
    --load-balancing-scheme=EXTERNAL \
    --global

• 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 Application 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 also deploys the URL map with the new configuration.

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

Console

To run tests from the Google Cloud console:

1. Go to the Load balancing page.

   Go to Load balancing

2. Click the Name of a load balancer.
3. On the Load Balancer Details page, click editEdit for the selected load balancer.
4. Click Routing rules. For a classic Application Load Balancer, this is Host and path rules.
5. Click Show configuration tests.
6. Click Add configuration test. Add the following test URLs and backends:
   • Test host and path 1 example.com and Backend www-service.
   • Test host and path 2 example.net and Backend www-service.
   • Test host and path 3 example.net/web and Backend www-service.
   • Test host and path 4 example.com/videos and Backend video-service.
   • Test host and path 5 example.com/videos/browse and Backend video-service.
   • Test host and path 6 example.net/static and Backend static-service.
   • Test host and path 7 example.net/static/images and Backend static-service.
7. Look for the blue checkmark to the left of Routing rules and click the Update button. For a classic Application Load Balancer, look for the blue check next to Host and path rules.

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

Console

You cannot list all of your URL maps in the Google 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

Console

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

1. Go to the Load balancing page.

   Go to Load balancing

2. Click the Name of a load balancer.
3. On the Load Balancer Details page, click editEdit 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

Console

To delete a URL map, perform the following steps:

1. Go to the Load balancing page.

   Go to Load balancing

2. Click the Name of a load balancer.
3. On the Load Balancer Details page, click editEdit for the selected load balancer.
4. On the Load Balancer Details page, 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]

Console

To delete a path matcher, perform the following steps:

1. Go to the Load balancing page.

   Go to Load balancing

2. Click the Name of a load balancer.
3. On the Load Balancer Details page, click editEdit 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]

Console

To delete a host rule, perform the following steps:

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

   Go to Load balancing

2. Click the Name of a load balancer.
3. On the Load Balancer Details page, click editEdit 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 altostrat.com from a URL map named my-map, you would run the following command:

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