Headers on

Header-based routing

Mon, 01 Jan 0001 00:00:00 +0000

Emissary can route to target services based on HTTP headers with the headers and regex_headers specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules.

The `headers` annotation

The headers attribute is a dictionary of header: value pairs. Emissary will only allow requests that match the specified header: value pairs to reach the target service.

Example

---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
 name: quote-backend
spec:
 prefix: /backend/
 service: quote
 headers:
 x-quote-mode: backend
 x-random-header: datawire

will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value datawire.

Add request headers

Mon, 01 Jan 0001 00:00:00 +0000

Emissary can add a dictionary of HTTP headers that can be added to each request that is passed to a service.

The `add_request_headers` attribute

The add_request_headers attribute is a dictionary of header: value pairs. The value can be a string, bool or object. When it is an object, the object should have a value property, which is the actual header value, and the remaining attributes are additional envoy properties.

Envoy dynamic values %DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT% and %PROTOCOL% are supported, in addition to static values.

Add response headers

Mon, 01 Jan 0001 00:00:00 +0000

Emissary can add a dictionary of HTTP headers that can be added to each response that is returned to the client.

The `add_response_headers` attribute

The add_response_headers attribute is a dictionary of header: value pairs. The value can be a string, bool or object. When it is an object, the object should have a value property, which is the actual header value, and the remaining attributes are additional envoy properties.

Envoy dynamic values %DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT% and %PROTOCOL% are supported, in addition to static values.

Remove request headers

Mon, 01 Jan 0001 00:00:00 +0000

Emissary can remove a list of HTTP headers that would be sent to the upstream from the request.

The `remove_request_headers` attribute

The remove_request_headers attribute takes a list of keys used to match to the header.

remove_request_headers can be set either in a Mapping or using ambassador Module defaults.

Mapping example

---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
 name: quote-backend
spec:
 prefix: /backend/
 remove_request_headers:
 - authorization
 service: quote

will drop the header with key authorization.

Remove response headers

Mon, 01 Jan 0001 00:00:00 +0000

Emissary can remove a list of HTTP headers that would be sent to the client in the response (e.g. default x-envoy-upstream-service-time).

The `remove_response_headers` attribute

The remove_response_headers attribute takes a list of keys used to match to the header.

remove_request_headers can be set either in a Mapping or using ambassador Module defaults.

Mapping example

---
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
 name: quote-backend
spec:
 prefix: /backend/
 remove_response_headers:
 - x-envoy-upstream-service-time
 service: quote

will drop the header with key x-envoy-upstream-service-time.

Host headers

Mon, 01 Jan 0001 00:00:00 +0000

Emissary supports several different methods for managing the HTTP Host header.

Using `host` and `host_regex`

A mapping that specifies the host attribute will take effect only if the HTTP Host header matches the value in the host attribute. If host_regex is true, the host value is taken to be a regular expression. Otherwise, an exact string match is required.

You may have multiple mappings listing the same resource but different host attributes to effect Host-based routing. An example:

Headers on

Header-based routing

The headers annotation

Example

Add request headers

The add_request_headers attribute

Add response headers

The add_response_headers attribute

Remove request headers

The remove_request_headers attribute

Mapping example

Remove response headers

The remove_response_headers attribute

Mapping example

Host headers

Using host and host_regex

The `headers` annotation

The `add_request_headers` attribute

The `add_response_headers` attribute

The `remove_request_headers` attribute

The `remove_response_headers` attribute

Using `host` and `host_regex`