Creating user-defined request headers

User-defined request headers allow you to specify additional headers that the load balancer adds to requests. These headers can include information that the load balancer knows about the client connection, including the latency to the client, the geographic location of the client's IP address, and parameters of the TLS connection.

User-defined request headers are supported for backend services associated with HTTP(S) load balancers.

Note that HTTP(S) load balancers add certain headers by default to all HTTP(S) requests that it proxies to backends. For more information on this, see Target proxies.

How user-defined request headers work

To enable user-defined request headers, you specify a list of headers in a property of the Backend Service resource. The load balancer adds the headers to the requests it forwards to the backends.

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 have the following properties:

  • The header name must be a valid HTTP header field definition (per RFC 7230, with obsolete forms disallowed).
  • The header name must not be X-User-IP and it must not begin with X-Google or X-GFE.
  • A header name must not appear more than once in the list of added headers.

Header values 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 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.

For example, you might specify a header with two variable names, for the client region and client city. The gcloud command-line tool has a flag for specifying request headers, --custom-request-header. For example:

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

The general format for the flag is:

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

The header values must be enclosed in curly braces. For example:

    --custom-request-header='X-PLACE:{client_city},{client_city_lat_long}'

Use only straight quotation marks (') in this command.

For more information on configuring custom request headers, read Working with user-defined request headers.

Variables that can appear in the header value

The following variables can appear in request header values.

Variable Description
client_rtt_msec Estimated round-trip transmission time between the load balancer and the HTTP(S) client, in milliseconds. This is the smoothed round-trip time (SRTT) parameter measured by the load balancer's TCP stack, per RFC 2988.
client_region The country (or region) associated with the client's IP address. This is a Unicode CLDR region code, such as "US" or "FR". (For most countries, these codes correspond directly to ISO-3166-2 codes.)
client_region_subdivision Subdivision, e.g. a province or state, of the country associated with the client's IP address. This is a Unicode CLDR subdivision ID, such as "USCA" or "CAON". (These Unicode codes are derived from the subdivisions defined by the ISO-3166-2 standard.)
client_city Name of the city from which the request originated, for example, "Mountain View" for Mountain View, California. There is no canonical list of valid values for this variable. The city names may contain US-ASCII letters, numbers, spaces, and the following characters: ``!#$%&'*+-.^_`|~``.
client_city_lat_long Latitude and Longitude of the city from which the request originated, for example, "37.386051,-122.083851" for a request from Mountain View.
tls_sni_hostname Server name indication (as defined in RFC 6066), if provided by the client during the TLS or QUIC handshake. The hostname is converted to lowercase and with any trailing dot removed.
tls_version TLS version negotiated between client and load balancer during the SSL handshake. Possible values include: "TLSv1", "TLSv1.1", "TLSv1.2", and, if the client connected using QUIC instead of TLS, "QUIC".
tls_cipher_suite Cipher suite negotiated during the TLS handshake. The value is four hex digits defined by the IANA TLS Cipher Suite Registry, for example, "009C for TLS_RSA_WITH_AES_128_GCM_SHA256. This value is empty for QUIC and for unencrypted client connections.

The load balancer expands variables to empty strings when it cannot determine their values, for example for geographic location variables when the IP address's location is unknown, or for TLS parameters when TLS is not in use.

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.

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

Working with user-defined request headers

The following limitations apply to user-defined request headers:

  • You can specify a maximum of 16 custom request headers per backend service.
  • The total size of all user-defined request headers per backend service (name and value combined, before variable expansion) cannot exceed 8 KB.

Console

To add custom request headers to an existing backend service:

  1. Go to the load balancing summary page.
    Go to the Load balancing page
  2. Click Backends.
  3. Click the name of a backend service.
  4. Click the Edit pencil.
  5. Click Advanced configurations (Session affinity, connection draining timeout, security policies).
  6. Under Custom request headers, click Add header.
  7. Enter the Header name and Header value for the custom request header.
  8. Enter any additional custom request headers.
  9. Click Save.

To remove a custom request header from a backend service:

  1. Go to the load balancing summary page. Go to the Load balancing page
  2. Click Backends.
  3. Click the name of a backend service.
  4. Click the Edit pencil.
  5. Click Advanced configurations (Session affinity, connection draining timeout, security policies).
  6. Click the X next to the name of the custom request header you want to remove.
  7. Click Save.

gcloud

To create a backend service with user-defined request headers:

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

To add more request headers, specify a unique header name and value by repeating the --custom-request-header flag.

To add user-defined request headers to an existing backend service:

gcloud compute backend-services update NAME \
  --global \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]' \
  --custom-request-header 'HEADER_NAME:[HEADER_VALUE]'

Note that the above replaces any headers already in the backend service with the request headers you specify in the command.

To remove all headers from a backend service:

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

API

Make a PATCH request to the backendServices.patch method.

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

What's next

For information about backend services, read Understanding backend services

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…