Create custom headers in URL maps Stay organized with collections Save and categorize content based on your preferences.

This page describes how custom headers work in URL maps used by regional external Application Load Balancers.

Custom request and response headers let you specify additional headers that the load balancer can add to HTTP(S) requests and responses. Depending on the information that the load balancer detects, these headers can include the following information:

• Latency to the client

• Parameters of the TLS connection

• Geographic location of the client's IP address

Before you begin

If necessary, update to the latest version of the Google Cloud CLI:

gcloud components update

How custom headers work

Custom headers work as follows:

• When the load balancer makes a request to the backend, the load balancer adds request headers.

  The load balancer adds custom request headers only to the client requests, not to the health check probes. If your backend requires a specific header for authorization that is missing from the health check packet, the health check might fail.

• The load balancer sets response headers before returning a response to the client.

To enable custom headers for regional external Application Load Balancers, you specify a list of header names and header values in the URL map configuration file.

Header names must have the following properties:

• The header name must be a valid HTTP header-field name definition per RFC 7230.
• The header name must not be X-User-IP.
• The header name must not begin with X-Google, X-Goog-, X-GFE, or X-Amz-.
• The following hop-by-hop headers must not be used: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, and Upgrade. In accordance with RFC 2616, these headers are not stored by caches or propagated by the target proxies.
• The header name must not be Host or authority. Both Host and authority are special keywords reserved by Google Cloud. You can't modify these headers for Envoy-based load balancers. Instead, we recommend that you create other custom headers (for example, MyHost) so that you don't interfere with the reserved header names.
• A header name must not appear more than once in the list of headers.

Header names are case-insensitive. When header names are passed to an HTTP/2 backend, the HTTP/2 protocol encodes header names as lowercase.

Header values must have the following properties:

• The header value must be a valid HTTP header field definition per RFC 7230, with obsolete forms disallowed.
• The header value can't be blank. Blank headers are rejected.
• The header value can include one or more variables, enclosed by curly braces, that expand to values that the load balancer provides. For a complete list of variables allowed in the header value, see Variables that can appear in the header value.

In header values, leading whitespace and trailing whitespace are insignificant and are not passed to the backend. To allow for curly braces in header values, the load balancer interprets two opening curly braces ({{) as a single opening brace ({), and two closing curly braces (}}) as a single closing brace (}).

Add request or response headers

To add request or response headers, use the gcloud CLI to edit the URL map as follows:

    gcloud compute url-maps edit URL_MAP_NAME \
        --region=REGION
    

   defaultService: projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1
   name: URL_MAP_NAME
   region: region/REGION
   hostRules:
   - hosts:
     - '*'
     pathMatcher: matcher1
   pathMatchers:
   - defaultService: projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1
     name: matcher1
     routeRules:
       - matchRules:
           - prefixMatch: /PREFIX
         priority: PRIORITY # 0 is highest
         routeAction:
           weightedBackendServices:
             - backendService: projects/PROJECT_ID/regions/REGION/backendServices/BACKEND_SERVICE_1
               weight: 100
               headerAction:
                 requestHeadersToAdd:
                 - headerName: X-header-1-client-region
                   headerValue: "{client_region}"
                 - headerName: X-header-2-client-ip-port
                   headerValue: "{client_ip_address}, {client_port}"
                   replace: True
                 requestHeadersToRemove:
                 - header-3-name
                 responseHeadersToAdd:
                 - headerName: X-header-4-server-ip-port
                   headerValue: "{server_ip_address}, {server_port}"
                   replace: True
                 responseHeadersToRemove:
                 - header-5-name
                 - header-6-name
    

Note the following behaviors:

• If a response header with custom variables resolves to an empty string, it is removed.
• If a request header with custom variables resolves to an empty string, it is retained with an empty string placeholder.
• If a custom request header includes a custom variable, and an incoming client request also includes the same header, the client request header value will be replaced with the new value provided by the load balancer's custom header.

Variables that can appear in the header value

The following variables can appear in custom header values.

The load balancer expands variables to empty strings when it can't determine their values. For example:

• TLS parameters when TLS is not in use

• The {origin_request_header} when the request does not include an Origin header

• Geographic location variables when the IP address's location is unknown

Geographic values are estimates based on the client's IP address. From time to time, Google updates the data that provides these values in order to improve accuracy and to reflect geographic and political changes. Even if the original X-Forwarded-For header contains valid location information, Google estimates client locations by using the source IP address information contained in packets received by the load balancer.

Mutual TLS custom headers

The following additional header variables are available if mutual TLS (mTLS) is configured on the load balancer's TargetHttpsProxy.

Limitations

The following limitations apply:

• You can't configure custom headers on backend services used by regional external Application Load Balancers.

• The following custom header variables aren't supported with regional external Application Load Balancers:

  • cdn_cache_id
  • cdn_cache_status
  • client_region_subdivision
  • client_city
  • client_city_lat_long