DocsEdge Stack2.2The Ambassador Module Resource
The Ambassador Module Resource
Contents
If present, the ambassador
Module
defines system-wide configuration for Ambassador Edge Stack. You may very well not need this resource. To use the ambassador
Module
to configure Ambassador Edge Stack, it MUST be named ambassador
, otherwise it will be ignored. To create multiple ambassador
Module
s in the same Kubernetes namespace, you will need to apply them as annotations with separate ambassador_id
s: you will not be able to use multiple CRDs.
The defaults in the ambassador
Module
are:
There are many config field items that can be configured on the ambassador
Module
. They are listed below with examples and grouped by category.
Envoy
Content-Length headers
allow_chunked_length: true
tells Envoy to allow requests or responses with bothContent-Length
andTransfer-Encoding
headers set.
By default, messages with both Content-Length
and Content-Transfer-Encoding
are rejected. If allow_chunked_length
is true
, Ambassador Edge Stack will remove the Content-Length
header and process the message. See the Envoy documentation for more details.
Envoy access logs
envoy_log_path
defines the path of Envoy's access log. By default this is standard output.envoy_log_type
defines the type of access log Envoy will use. Currently, onlyjson
ortext
are supported.envoy_log_format
defines the Envoy access log line format.
These logs can be formatted using Envoy operators to display specific information about an incoming request. The example below will show only the protocol and duration of a request:
See the Envoy documentation for the standard log format and a complete list of log format operators.
Envoy validation timeout
envoy_validation_timeout
defines the timeout, in seconds, for validating a new Envoy configuration.
The default is 10; a value of 0 disables Envoy configuration validation. Most installations will not need to use this setting.
For example:
would allow 30 seconds to validate the generated Envoy configuration.
Error response overrides
error_response_overrides
permits changing the status code and body text for 4XX and 5XX response codes.
By default, Ambassador Edge Stack will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any.
See using error response overrides for usage details. For example, this configuration:
would explicitly modify the body of 404s to say "File not found".
Forwarding client cert details
Two attributes allow providing information about the client's TLS certificate to upstream certificates:
forward_client_cert_details: true
will tell Envoy to add theX-Forwarded-Client-Cert
to upstream requests.set_current_client_cert_details
will tell Envoy what information to include in theX-Forwarded-Client-Cert
header.
Ambassador Edge Stack will not forward information about a certificate that it cannot validate.
See the Envoy documentation on X-Forwarded-Client-Cert and SetCurrentClientCertDetails for more information.
Server name
server_name
allows overriding the server name that Envoy sends with responses to clients.
By default, Envoy uses a server name of envoy
.
Suppress Envoy headers
suppress_envoy_headers: true
will prevent Ambassador Edge Stack from emitting certain additional headers to HTTP requests and responses.
For the exact set of headers covered by this config, see the Envoy documentation
General
Ambassador ID
ambassador_id
allows using multiple instances of Ambassador Edge Stack in the same cluster.
We recommend not setting ambassador_id
if you are running only one instance of Ambassador Edge Stack in your cluster. For more information, see the Running and Deployment documentation.
If used, the ambassador_id
value must be an array, for example:
Defaults
defaults
provides a dictionary of default values that will be applied to various Ambassador Edge Stack resources.
See Using ambassador
Module
Defaults for more information.
gRPC
Bridges
enable_grpc_http11_bridge: true
will enable the gRPC-HTTP/1.1 bridge.enable_grpc_web: true
will enable the gRPC-Web bridge.
gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments).
The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with Content-Type: application/grpc
into gRPC calls: Ambassador Edge Stack will perform buffering and translation as necessary. For more details on the translation process, see the Envoy gRPC HTTP/1.1 bridge documentation.
Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and Ambassador Edge Stack can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the Envoy gRPC HTTP/1.1 bridge documentation; for more details on gRPC-Web itself, see the gRPC-Web client GitHub repo.
Statistics
grpc_stats
allows enabling telemetry for gRPC calls using Envoy's gRPC Statistics Filter.
Supported parameters:
all_methods
services
upstream_stats
Available metrics:
envoy_cluster_grpc_<service>_<status_code>
envoy_cluster_grpc_<service>_request_message_count
envoy_cluster_grpc_<service>_response_message_count
envoy_cluster_grpc_<service>_success
envoy_cluster_grpc_<service>_total
envoy_cluster_grpc_upstream_<stats>
- only whenupstream_stats: true
Please note that <service>
will only be present if all_methods
is set or the service and the method are present under services
. If all_methods
is false or the method is not on the list, the available metrics will be in the format envoy_cluster_grpc_<stats>
.
all_methods
: If set to true, emit stats for all service/method names. If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.services
: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric).
upstream_stats
: If true, the filter will gather a histogram for the request time of the upstream.
Header behavior
Header case
proper_case: true
forces headers to have their "proper" case as shown in RFC7230.header_case_overrides
allows forcing certain headers to have specific casing.
RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP:
Host
, nothost
orHOST
Content-Type
, notcontent-type
,Content-type
, orcOnTeNt-TyPe
Internally, Envoy typically uses all lowercase for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting proper_case: true
will tell Envoy to force all headers to use the casing above.
Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. header_case_overrides
specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match X-MY-Header
and X-EXPERIMENTAL
to use that exact casing, regardless of the original case used in flight:
If the upstream service responds with x-my-header: 1
, Ambassador Edge Stack will return X-MY-Header: 1
to the client. Similarly, if the client includes x-ExperiMENTAL: yes
in its request, the request to the upstream service will include X-EXPERIMENTAL: yes
. Other headers will not be altered; Ambassador Edge Stack will use its default lowercase header.
Please see the Envoy documentation for more information. Note that in general, we recommend updating clients and services rather than relying on header_case_overrides
.
Linkerd interoperability
add_linkerd_headers: true
will force Ambassador Edge Stack to include thel5d-dst-override
header for Linkerd.
When using older Linkerd installations, requests going to an upstream service may need to include the l5d-dst-override
header to ensure that Linkerd will route them correctly. Setting add_linkerd_headers
does this automatically. See the Mapping documentation for more details.
Max request headers size
max_request_headers_kb
sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB.
See Envoy documentation for more information.
Preserve external request ID
preserve_external_request_id: true
will preserve anyX-Request-Id
header presented by the client. The default isfalse
, in which case Envoy will always generate a newX-Request-Id
value.
Strip matching host port
strip_matching_host_port: true
will tell Ambassador Edge Stack to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default isfalse
, which will preserve any port number.
In the default installation of Ambassador Edge Stack the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match.
A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. myurl.com:443
). We have an alternative solution in our gRPC guide that uses a Lua script to remove all ports from every Host header for that use case.
Miscellaneous
Envoy's admin port
admin_port
specifies the port where Ambassador Edge Stack's Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing.
Lua scripts
lua_scripts
allows defining a custom Lua script to run on every request.
This is useful for simple use cases that mutate requests or responses, for example to add a custom header:
For more details on the Lua API, see the Envoy Lua filter documentation.
Some caveats around the embedded scripts:
- They run in-process, so any bugs in your Lua script can break every request.
- They're run on every request/response to every URL.
- They're inlined in the Ambassador Edge Stack YAML; as such, we do not recommend using Lua scripts for long, complex logic.
If you need more flexible and configurable options, Ambassador Edge Stack supports a pluggable Filter system.
Merge slashes
merge_slashes: true
will cause Ambassador Edge Stack to merge adjacent slashes in incoming paths when doing route matching and request filtering: for example, a request for//foo///bar
would be matched to aMapping
with prefix/foo/bar
.
Modify Default Buffer Size
By default, the Envoy that ships with Ambassador Edge Stack uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the Envoy docs for more information.
Use Ambassador Edge Stack namespace for service resolution
use_ambassador_namespace_for_service_resolution: true
tells Ambassador Edge Stack to assume that unqualified services are in the same namespace as Ambassador Edge Stack
By default, when Ambassador Edge Stack sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this Mapping
:
Ambassador Edge Stack would look for a Service named upstream
in namespace foo
.
However, if use_ambassador_namespace_for_service_resolution
is true
, this Mapping
would look for a Service named foo
in the namespace in which Ambassador Edge Stack is installed instead.
Observability
Diagnostics
diagnostics
controls access to the diagnostics interface.
By default, Ambassador Edge Stack creates a Mapping
that allows access to the diagnostic interface at /ambassador/v0/diag
from anywhere in the cluster. To disable the Mapping
entirely, set diagnostics.enabled
to false
:
With diagnostics disabled, /ambassador/v0/diag
will respond with 404; however, the service itself is still running, and /ambassador/v0/diag/
is reachable from inside the Ambassador Edge Stack Pod at https://localhost:8877
. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily:
Alternately, to leave the Mapping
intact but restrict access to only the local Pod, set diagnostics.allow_non_local
to false
:
See Protecting Access to the Diagnostics Interface for more information.
Protocols
Enable IPv4 and IPv6
enable_ipv4
determines whether IPv4 DNS lookups are enabled. The default istrue
.enable_ipv6
determines whether IPv6 DNS lookups are enabled. The default isfalse
.
If both IPv4 and IPv6 are enabled, Ambassador Edge Stack will prefer IPv6. This can have strange effects if Ambassador Edge Stack receives AAAA
records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only.
A Mapping
can override both enable_ipv4
and enable_ipv6
, but if either is not stated explicitly in a Mapping
, the values here are used. Most Ambassador Edge Stack installations will probably be able to avoid overriding these settings in Mappings.
HTTP/1.0 support
enable_http10: true
will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default isfalse
.
Security
Cross origin resource sharing (CORS)
cors
sets the default CORS configuration for all mappings in the cluster. See the CORS syntax.
For example:
IP allow and deny
ip_allow
andip_deny
define HTTP source IP address ranges to allow or deny.
The default is to allow all traffic.
If ip_allow
is specified, any traffic not matching a range to allow will be denied. If ip_deny
is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified.
Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example:
The keyword peer
specifies that the match should happen using the IP address of the other end of the network connection carrying the request: X-Forwarded-For
and the PROXY
protocol are both ignored. Here, our example specifies that connections originating from the Ambassador Edge Stack pod itself should always be allowed.
The keyword remote
specifies that the match should happen using the IP address of the HTTP client, taking into account X-Forwarded-For
and the PROXY
protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, Ambassador Edge Stack is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range 99.99.0.0
- 99.99.255.255
will be allowed.
You may specify as many ranges for each kind of keyword as desired.
Rejecting Client Requests With Escaped Slashes
reject_requests_with_escaped_slashes: true
will tell Ambassador Edge Stack to reject requests containing escaped slashes.
When set to true
, Ambassador Edge Stack will reject any client requests that contain escaped slashes (%2F
, %2f
, %5C
, or %5c
) in their URI path by returning HTTP 400. By default, Ambassador Edge Stack will forward these requests unmodified.
Envoy and Ambassador Edge Stack behavior
Internally, Envoy treats escaped and unescaped slashes distinctly for matching purposes. This means that an Ambassador Edge Stack mapping for path
/httpbin/status
will not be matched by a request for/httpbin%2fstatus
.On the other hand, when using Ambassador Edge Stack, escaped slashes will be treated like unescaped slashes when applying FilterPolicies. For example, a request to
/httpbin%2fstatus/200
will be matched against a FilterPolicy for/httpbin/status/*
.Security Concern Example
With Ambassador Edge Stack, this can become a security concern when combined with
bypass_auth
in the following scenario:Use a
Mapping
for path/prefix
withbypass_auth
set to true. The intention here is to apply no FilterPolicies under this prefix, by default.Use a
Mapping
for path/prefix/secure/
without setting bypass_auth to true. The intention here is to selectively apply a FilterPolicy to this longer prefix.Have an upstream service that receives both
/prefix
and/prefix/secure/
traffic (from the Mappings above), but the upstream service treats escaped and unescaped slashes equivalently.
In this scenario, when a client makes a request to
/prefix%2fsecure/secret.txt
, the underlying Envoy configuration will not match the routing rule for/prefix/secure/
, but will instead match the routing rule for/prefix
which hasbypass_auth
set to true. Ambassador Edge Stack FilterPolicies will not be enforced in this case, and the upstream service will receive a request that it treats equivalently to/prefix/secure/secret.txt
, potentially leaking information that was assumed protected by an Ambassador Edge Stack FilterPolicy.One way to avoid this particular scenario is to avoid using
bypass_auth
and instead use a FilterPolicy that applies no filters when no authorization behavior is desired.The other way to avoid this scenario is to reject client requests with escaped slashes altogether to eliminate this class of path confusion security concerns. This is recommended when there is no known, legitimate reason to accept client requests that contain escaped slashes. This is especially true if it is not known whether upstream services will treat escaped and unescaped slashes equivalently.
This document is not intended to provide an exhaustive set of scenarios where path confusion can lead to security concerns. As part of good security practice it is recommended to audit end-to-end request flow and the behavior of each component’s escaped path handling to determine the best configuration for your use case.
Summary
Envoy treats escaped and unescaped slashes distinctly for matching purposes. Matching is the underlying behavior used by Ambassador Edge Stack Mappings.
Ambassador Edge Stack treats escaped and unescaped slashes equivalently when selecting FilterPolicies. FilterPolicies are applied by Ambassador Edge Stack after Envoy has performed route matching.
Finally, whether upstream services treat escaped and unescaped slashes equivalently is entirely dependent on the upstream service, and therefore dependent on your use case. Configuration intended to implement security policies will require audit with respect to escaped slashes. By setting reject_requests_with_escaped_slashes, this class of security concern can largely be eliminated.
Trust downstream client IP
use_remote_address: false
tells Ambassador Edge Stack that it cannot trust the remote address of incoming connections, and must instead rely exclusively on theX-Forwarded-For
header.
When true
(the default), Ambassador Edge Stack will append its own IP address to the X-Forwarded-For
header so that upstream services of Ambassador Edge Stack can get the full set of IP addresses that have propagated a request. You may also need to set externalTrafficPolicy: Local
on your LoadBalancer
to propagate the original source IP address.
See the Envoy documentation on the X-Forwarded-For header
and the Kubernetes documentation on preserving the client source IP for more details.
X-Forwarded-For
trusted hops
xff_num_trusted_hops
sets how many L7 proxies ahead of Ambassador Edge Stack should be trusted.
The value of xff_num_trusted_hops
indicates the number of trusted proxies in front of Ambassador Edge Stack. The default setting is 0 which tells Envoy to use the immediate downstream connection's IP address as the trusted client address. The trusted client address is used to populate the remote_address
field used for rate limiting and can affect which IP address Envoy will set as X-Envoy-External-Address
.
xff_num_trusted_hops
behavior is determined by the value of use_remote_address
(which is true by default).
If
use_remote_address
is false andxff_num_trusted_hops
is set to a value N that is greater than zero, the trusted client address is the (N+1)th address from the right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the immediate downstream connection’s source address as a trusted client address.)If
use_remote_address
is true andxff_num_trusted_hops
is set to a value N that is greater than zero, the trusted client address is the Nth address from the right end of XFF. (If the XFF contains fewer than N addresses, Envoy falls back to using the immediate downstream connection’s source address as a trusted client address.)
Refer to Envoy's documentation for some detailed examples of this interaction.
Service health / timeouts
Incoming connection idle timeout
listener_idle_timeout_ms
sets the idle timeout for incoming connections.
If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of Ambassador Edge Stack and need to control how Ambassador Edge Stack initiates closing an idle TCP connection.
If not set, the default is no timeout, meaning that incoming connections may remain idle forever.
Please see the Envoy documentation on HTTP protocol options for more information.
Keepalive
keepalive
sets the global TCP keepalive settings.
Ambassador Edge Stack will use these settings for all Mapping
s unless overridden in a Mapping
's configuration. Without keepalive
, Ambassador Edge Stack follows the operating system defaults.
For example, the following configuration:
would enable keepalives every two seconds (interval
), starting after two seconds of idleness (time
), with the connection being dropped if 100 keepalives are sent with no response (probes
). For more information, see the Envoy keepalive documentation.
Upstream idle timeout
cluster_idle_timeout_ms
sets the default idle timeout for upstream connections (by default, one hour).
If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting cluster_idle_timeout_ms: 0
, which risks idle upstream connections never getting closed.
If not set, the default idle timeout is one hour.
You can override this setting with idle_timeout_ms
on a Mapping
.
Upstream max lifetime
cluster_max_connection_lifetime_ms
sets the default maximum lifetime of an upstream connection.
If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime.
If not set (or set to zero), then upstream connections may remain open for arbitrarily long.
You can override this setting with cluster_max_connection_lifetime_ms
on a Mapping
.
Request timeout
cluster_request_timeout_ms
sets the default end-to-end timeout for a single request.
If set, this specifies the default end-to-end timeout for every request.
If not set, the default is three seconds.
You can override this setting with timeout_ms
on a Mapping
.
Readiness and liveness probes
readiness_probe
sets whether/ambassador/v0/check_ready
is automatically mappedliveness_probe
sets whether/ambassador/v0/check_alive
is automatically mapped
By default, Ambassador Edge Stack creates Mapping
s that support readiness and liveness checks at /ambassador/v0/check_ready
and /ambassador/v0/check_alive
. To disable the readiness Mapping
entirely, set readiness_probe.enabled
to false
:
Likewise, to disable the liveness Mapping
entirely, set liveness_probe.enabled
to false
:
A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the Ambassador Edge Stack Pod.
You can change these to route requests to some other service. For example, to have the readiness probe map to the quote
application's health check:
The liveness and readiness probes both support prefix
and rewrite
, with the same meanings as for Mappings.
Retry policy
This lets you add resilience to your services in case of request failures by performing automatic retries.
Traffic management
Circuit breaking
circuit_breakers
sets the global circuit breaking configuration defaults
You can override the circuit breaker settings for individual Mapping
s. By default, Ambassador Edge Stack does not configure any circuit breakers. For more information, see the circuit breaking reference.
Default label domain and labels
default_labels
sets default domains and labels to apply to every request.
For more on how to use the default labels, , see the Rate Limit reference.
Default load balancer
load_balancer
sets the default load balancing type and policy
For example, to set the default load balancer to least_request
:
If not set, the default is to use round-robin load balancing. For more information, see the load balancer reference.