Create custom headers in backend services

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 detected by the load balancer, these headers can include the following information:

• Latency to the client
• Geographic location of the client's IP address
• Parameters of the TLS connection

Custom request headers are supported for backend services, while custom response headers are supported for backend services and backend buckets.

The load balancer adds certain headers by default to all HTTP(S) requests and responses that it proxies between backends and clients. For more information, see Target proxies .

Custom headers in URL maps

Global external Application Load Balancers support a similar feature for header transformation in the URL map . While you can manage custom headers in backend services (as described on this page), we recommend putting your header transformations in the URL map so that all of your header transformations are maintained in a single location.

If custom header configurations are present in both the URL map and the backend service, both configurations are applied. However, if the same header is set in both the backend service and the URL map, the URL map takes precedence and the backend service setting is ignored. For a URL map-based example, see Set up traffic management for global external Application Load Balancers .

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 forwards 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 the responses to the client.

To enable custom headers, you specify a list of headers in a property of the backend service or backend bucket.

You specify each header as a header-name:header-value string. The header must contain a colon separating the header name and header value.

Header names must fulfill the following requirements:

• The header name must be a valid HTTP header-field name definition (per RFC 7230 ).
• The Host header can be configured, but is subject to certain limitations .
• The header name must not be authority . This is a special keyword reserved by Google Cloud. You can't modify this header for Envoy-based load balancers such as the global external Application Load Balancer. Instead, we recommend that you create other custom headers so that you don't interfere with reserved header names.
• The header name must not be X-User-IP or CDN-Loop .
• 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 begin with X-Google , X-Goog- , X-GFE or X-Amz- .
• A header name must not appear more than once in the list of added headers.

Header values must fulfill the following requirements:

• The header value must be a valid HTTP header field definition per RFC 7230 , with obsolete forms disallowed).
• The header value can be blank.
• The header value can include one or more variables, enclosed by curly braces, that expand to values that the load balancer provides. A list of variables allowed in the header value is in the next section.

The gcloud command-line tool has a flag for specifying request headers, which is --custom-request-header . Make sure to enclose the header name and header value in straight single quotes ( ' ) with this flag.

The general format for the flag is:

--custom-request-header='HEADER_NAME:[HEADER_VALUE]'

The following is an example of a header value with two variables, client_region and client_city , enclosed in curly braces.

--custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'

For clients located in Mountain View, California, the load balancer adds a header as follows:

X-Client-Geo-Location:US,Mountain View

Host headers

The following limitations apply when you're configuring a custom Host header with a global external Application Load Balancer:

• You can only configure a custom Host request header if you're replacing an existing Host request header.
• You can't configure a custom Host response header by using header actions in the URL map . However, you can still configure the custom Host response header in the backend service.
• Additionally, the following apply to both request and response headers:
  • You can't append or remove custom Host headers.
  • You can't use variables with custom Host headers.

Variables supported with header values

The following variables can appear in custom header values.

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

• Geographic location variables when the IP address's location is unknown
• TLS parameters when TLS is not in use
• The {origin_request_header} when the request does not include an Origin header
• The {cdn_cache_status} header when included in a request header

Geographic values (regions, subdivisions, and cities) 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.

Headers added by the load balancer overwrite any existing headers that have the same name. Header names are case insensitive. When header names are passed to an HTTP/2 backend, the HTTP/2 protocol encodes header names as lower case.

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 ( } ).

Mutual TLS custom headers

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

Configure custom request headers

gcloud compute backend-services create BACKEND_SERVICE_NAME 
\
    --global-health-checks \
    --global \
    --protocol HTTPS \
    --health-checks https-basic-check \
    --custom-request-header=' HEADER_NAME 
:[ HEADER_VALUE 
]'

gcloud compute backend-services update BACKEND_SERVICE_NAME 
\
    --global \
    --custom-request-header=' HEADER_1_NAME 
:[ HEADER_1_VALUE 
]' \
    --custom-request-header=' HEADER_2_NAME 
:[ HEADER_2_VALUE 
]'

gcloud compute backend-services update BACKEND_SERVICE_NAME 
\
    --global \
    --no-custom-request-headers

PATCH https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID 
/global/backendServices/ BACKEND_SERVICE_NAME 
"customRequestHeaders": [
   "client_city:Mountain View"
]

Configure custom response headers

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME 
--custom-response-header=' HEADER_NAME 
:[ HEADER_VALUE 
]'

gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME 
--custom-response-header=' HEADER_NAME 
:[ HEADER_VALUE 
]'

gcloud compute backend-buckets update gaming-lab \
    --custom-response-header='X-Frame-Options: DENY'

gcloud compute backend-services update customer-bs-name \
    --global \
    --custom-response-header='Strict-Transport-Security: max-age=63072000'

POST https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID 
/global/backendBuckets

PUT https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID 
/global/backendBuckets/ BACKEND_BUCKET_NAME 
POST https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID 
/global/backendServices

PUT https://compute.googleapis.com/compute/v1/projects/ PROJECT_ID 
/global/backendServices/ BACKEND_SERVICE_NAME 

"customResponseHeaders": HEADER_NAME 
:[ HEADER_VALUE 
]

Set response headers for Cloud Storage

If you need to set HTTP headers on responses from Cloud Storage—such as Cross-Origin Resource Policy, X-Frame-Options , or X-XSS-Protection headers—Google Cloud offers the option to use custom headers for Cloud CDN with Cloud Storage. You can do this by configuring custom headers at the load balancer backend bucket level, as described on this page.

Custom response headers configured at the backend bucket level are only added to responses if the client request is sent to the load balancer IP address. Custom headers are not added to responses if the client's request was made directly to the Cloud Storage API.

Use custom headers with Google Cloud Armor

When you configure a Cloud Armor security policy, you can configure Cloud Armor to insert a custom header and value. If your Cloud Armor security policy is configured to insert the same custom header name as your global external Application Load Balancer or classic Application Load Balancer's custom headers, then the header value specified in your Cloud Armor security policy is overwritten by the value populated by the load balancer. If you don't want the Cloud Armor policy to be overwritten, ensure that you don't use the same name.

Limitations

The following limitations apply to custom headers used with global load balancers:

• The total size of all custom request headers (name and value combined, before variable expansion) for each backend service must not exceed 8 KB or 16 request headers.
• The total size of all custom response headers (name and value combined, before variable expansion) for each backend service must not exceed 8 KB or 16 response headers.