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 can't 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