This document provides example configurations of custom error responses. Beforeyou configure a custom error response, read theCustom error response overview.

The example configurations described on this page configure a custom errorresponse policy at three levels of theURL map resource—the load balancerlevel, the URL domain level, and the URL path level.

The example configurations draw on concepts and buildon setups described in the following documents:

• Set up a global external Application Load Balancer with VM instance groupbackends
• Create backendbuckets
• How URL maps work
• Configure URL maps

Example 1: Configure an error page for all4xx errors common to all hosts

This example assumes that you have set up a loadbalancer as described inSet up a global external Application Load Balancer with VM instancegroup backends.

In this example, requests to the load balancer are routed to the backend servicenamedweb-backend-service. If the request encounters a4xx response, thecustom error response policy is configured to then send the request to theerror service, and an error object (not-found.html) is returned to the client.

To create a custom error response policy, follow these steps:

1. Upload the HTML error page (not-found.html) to the Cloud Storage bucket.

   gcloud storage cp Desktop/not-found.html gs://GCS_BUCKET_NAME/

2. Export the URL map (web-map-http) into a file namedweb-map-http.yaml.

   gcloud compute url-maps export web-map-http --destination web-map-http.yaml

   Before you add the custom error response policy, the URL map (web-map-http)has a configuration similar to the following.

   creationTimestamp: '2020-01-14T19:12:44.680-08:00'defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-servicefingerprint: d0eJJpCBpHg=kind: compute#urlMapname: web-map-httpselfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http

3. Editweb-map-http.yaml to add a custom error response policy as highlightedin the following YAML configuration, in thedefaultCustomErrorResponsePolicy section. In this example, an errorresponse policy is configured at the load balancer level(urlMaps.defaultCustomErrorResponsePolicy).

   creationTimestamp: '2020-01-14T19:12:44.680-08:00'defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-servicedefaultCustomErrorResponsePolicy:  errorResponseRules:    - matchResponseCodes:      - 4xx      path: '/not-found.html'  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKETfingerprint: d0eJJpCBpHg=kind: compute#urlMapname: web-map-httpselfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-http

   We recommend that you store all your error objects in a Cloud Storagebucket and have them referenced by a backend bucket attached to your loadbalancer. Cloud Storage buckets provide a simple way for you to storeyour error objects and have them returned to your clients by using the loadbalancer. However,you can also serve error pages and related assets without using a backendbucket. For example, you can use a backend service, which references a VMinstance group backend that has an Apache server configured to serve a customerror response page.

4. Update the URL map by importing the latest configuration fromweb-map-http.yaml.

   gcloud compute url-maps import web-map-http --source web-map-http.yaml

5. After you update the URL map, you need to wait for some time before you canstart sending traffic to your load balancer's IP address.

   Send a request for a page that does not exist.

   curl -I http://IP_ADDRESS/a-page-that-does-not-exist

   The error content fromnot-found.html is served and an HTTP404 status codeis returned.

Example 2: Configure an error page for a specific error code for a specific host

This example builds on the previous example—Configure an error page forall4xx errors common to all hosts. It assumes that a loadbalancer is already configured such that requests to the hostvideo.example.com are routed to the backend service namedvideo-backend-service. If a request fails authorization by the backendservice, the service returns a401 (Unauthorized) response. The custom errorresponse policy is configured to then send the request to the error service, andan error object (video-obtain-authorization.html) is returned to the client.

In most cases, your error content is likely to contain links to assets—forexample, a logo image. The client makes requests for assets referenced in theerror page, and additional requests are sent to the load balancer to fetch them.The load balancer then responds to the request and returns the linked assets.This is accomplished by storing these assets in the same backend bucketspecified indefaultCustomErrorResponsePolicy and adding a rule to routerequests from asset URLs (for example,/assets/logo.svg) to the backendbucket. The load balancer's response to the request for linked assets is not anerror response, but a normal response, as shown in the following configuration.

pathMatchers:...  pathRules:  - service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET    paths:    - /assets

The policy also lets you define what the final response code for the requestshould be. In this example, the response code has changed from401 to200by specifying the value ofoverrideResponseCode to200. For all other4xxerrors, the error content innot-found.html is returned to the client, and theoriginal HTTP response code from the backend service is preserved.

As shown in the following table, two custom error response policies areconfigured in this example. These policies are created at the load balancerlevel and the URL domain level.

To create a custom error response policy for a401 error code for the hostvideo.example.com, follow these steps:

1. Upload the HTML error page (video-obtain-authorization.html) and relatedassets (logo.svg) to the Cloud Storage bucket.

   gcloud storage cp Desktop/video-obtain-authorization.html gs://GCS_BUCKET_NAME/gcloud storage cp Desktop/logo.svg gs://GCS_BUCKET_NAME/assets/

2. Export the URL map (web-map-http) into a file namedweb-map-http.yaml.

   gcloud compute url-maps export web-map-http --destination web-map-http.yaml

3. Editweb-map-http.yaml to add a custom error response policy as highlightedin the following YAML configuration, in thedefaultCustomErrorResponsePolicy section. In this example, a custom errorresponse policy is configured at the load balancer level(urlMaps.defaultCustomErrorResponsePolicy) and the URL domain level(pathMatchers[].defaultCustomErrorResponsePolicy).

   Because the error service is not defined at the URL domain level, the errorservice at the URL domain level defaults to the error service defined at thehigher level; that is, the load balancer level.

   creationTimestamp: '2020-01-14T19:12:44.680-08:00'defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/web-backend-servicedefaultCustomErrorResponsePolicy:  errorResponseRules:    - matchResponseCodes:      - 4xx      path: '/not-found.html'  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKETfingerprint: d0eJJpCBpHg=hostRules:- hosts:  - video.example.com  pathMatcher: path-matcher-1kind: compute#urlMapname: web-map-httpselfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/web-map-httppathMatchers:- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-backend-service  name: path-matcher-1  defaultCustomErrorResponsePolicy:    errorResponseRules:      - matchResponseCodes:        - 401        path: "/video-obtain-authorization.html        overrideResponseCode: 200    // The `errorService` in `pathMatchers[].defaultCustomErrorResponsePolicy` references the    // error service configured in `urlMaps.defaultCustomErrorResponsePolicy`.  // A URL map path rule to route requests from asset URLs (for example, "/assets/logo.svg") to the backend bucket.  pathRules:  - service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/CUSTOM_ERRORS_BUCKET    paths:    - /assets

4. Update the URL map by importing the latest configuration fromweb-map-http.yaml.

   gcloud compute url-maps import web-map-http --source web-map-http.yaml

5. After you update the URL map, you need to wait for some time before you canstart sending traffic to your load balancer's IP address.

   Send a request to your host for a URL that needs authorization.

   curl -I http://video.example.com/a-page-that-needs-authorization

   The error content fromvideo-obtain-authorization.html is served, and an HTTP200 status code is returned.

Example 3: Configure granular custom error response policies for different domains, paths, and error response codes

This example shows how you can customize specific error responses for differentURL domains, URL paths, and HTTP error response codes.

The custom error response configuration, explained in this example, assumes thefollowing:

• You haveconfigured a URL map for anexternal Application Load Balancerwith a host and path-based routing as depicted in the following image.

  

• You have configured two backend buckets namedBUCKET_1 andBUCKET_2 toreturn the custom error pages.

As shown in the following table, four custom error response policies areconfigured in this example. These policies are created across threelevels in the following order of precedence:

1. URL path (pathMatchers[].pathRules[].customErrorResponsePolicy)
2. URL domain (pathMatchers[].defaultCustomErrorResponsePolicy)
3. Load balancer (urlMaps.defaultCustomErrorResponsePolicy)

The custom error response policy at theload balancer level is applied only ifthe policy matches the error conditions and no matching policy has been definedfor the error code at the lower levels; that is, the URL domain or the URL path.Similarly, the custom error response policy at theURL domain level is appliedonly if the policy matches the error conditions and no matching policy has beendefined for the error code at the lower level; that is, the URL path. In thisexample, if a request to the URLwww.example.net/video/hd encounters a404response, then the filenot-found-hd-videos-404.html is returned. However, ifa404 response is encountered for a request to the URLwww.example.net/video/,then the fileexample-net-4xx.html is returned.

To create custom error response policies across three levels of the URL map,follow these steps:

1. Upload the error objects to the Cloud Storage buckets.

   gcloud storage cp Desktop/error-page-generic.html gs://GCS_BUCKET_1_NAME/gcloud storage cp Desktop/example-net-4xx.html gs://GCS_BUCKET_1_NAME/gcloud storage cp Desktop/not-found-sd-videos-404.html gs://GCS_BUCKET_2_NAME/gcloud storage cp Desktop/not-found-hd-videos-404.html gs://GCS_BUCKET_2_NAME/

2. Export the URL map (video-org-url-map) into a file namedvideo-org-url-map.yaml.

   gcloud compute url-maps export video-org-url-map --destination video-org-url-map.yaml

   Before you add the custom error response policy, the URL map(video-org-url-map) has a configuration similar to the following.

   creationTimestamp: '2021-03-05T13:34:15.833-08:00'defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-sitefingerprint: mfyJIT7Zurs=hostRules:- hosts:  - '*'  pathMatcher: video-matcher- hosts:  - example.net  pathMatcher: video-matcherid: '8886405179645041976'kind: compute#urlMapname: video-org-url-mappathMatchers:- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site  name: video-matcher  pathRules:  - paths:    - /video/hd    - /video/hd/*    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd  - paths:    - /video/sd    - /video/sd/*    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sdselfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

3. Editvideo-org-url-map.yaml to add custom error response policies ashighlighted in the following YAML configuration, in thedefaultCustomErrorResponsePolicy section.

   Because the error service is not defined at the URL domain level, the errorservice at the URL domain level defaults to the error service defined at thehigher level; that is, the load balancer level.

   creationTimestamp: '2021-03-05T13:34:15.833-08:00'defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/org-sitefingerprint: mfyJIT7Zurs=hostRules:- hosts:  - '*'  pathMatcher: video-matcher- hosts:  - example.net  pathMatcher: video-matcherid: '8886405179645041976'kind: compute#urlMapname: video-org-url-mapdefaultCustomErrorResponsePolicy:  errorResponseRules:    - matchResponseCodes:      - 4xx      - 5xx      path: '/error-page-generic.html'  errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-1pathMatchers:- defaultService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-site  name: video-matcher  defaultCustomErrorResponsePolicy:      errorResponseRules:        - matchResponseCodes:          - 4xx          path: '/example-net-4xx.html'      // The `errorService` in `pathMatchers[].defaultCustomErrorResponsePolicy` references the      // error service configured in `urlMaps.defaultCustomErrorResponsePolicy`.  pathRules:  - paths:    - /video/hd    - /video/hd/*    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-hd    customErrorResponsePolicy:          errorResponseRules:            - matchResponseCodes:              - 404              path: '/not-found-hd-videos-404.html'          errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-2  - paths:    - /video/sd    - /video/sd/*    service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/video-sd    customErrorResponsePolicy:          errorResponseRules:            - matchResponseCodes:              - 404              path: '/not-found-sd-videos-404.html'          errorService: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BUCKET-2selfLink: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/urlMaps/video-org-url-map

4. Update the URL map by importing the latest configuration fromvideo-org-url-map.yaml.

   gcloud compute url-maps import video-org-url-map --source video-org-url-map.yaml

5. After you update the URL map, you need to wait for some time before you canstart sending traffic to your load balancer's IP address.

   Send a request for a page that does not exist.

   curl -I http://example.net/a-page-that-does-not-exist

   The error content fromexample-net-4xx.html is served.

   Similarly, test for other URLs with different URL domains and URL paths.