Defaults
Everything the format has no key for is the same in every configuration the Envoy generator writes, and this page says what that is.
- One public listener on
0.0.0.0, so a container runtime can publish the port. It serves plain HTTP unlesstlsis written. Who may reach it is the network's rule, not the gateway's. Each service gets one cluster for each port it declares, named<service>_httpand<service>_grpc, with no TLS to the service. - One backend at
127.0.0.1for a service that writes neitheraddressnoraddresses. Requests are spread round robin whenbalanceis not written, and a DNS name inaddressis asked of the host's resolver configuration whendnsis not written. Withouthealthevery backend stays in the pool. - A DNS name is looked up for its IPv4 and IPv6 addresses both (
dns_lookup_family: ALLin the cluster'sDnsCluster), whether it is a service's address, the tracing endpoint or the keys URL's host, and each address is a backend. Envoy's own default asks for IPv6 addresses first and for IPv4 ones only when there are none (Backends and balancing). - A cluster that looks a name up is Envoy's
DnsClusterextension in the cluster'scluster_type, withdns_lookup_familyanddns.resolverinside it, because Envoy 1.40.2 deprecates the DNS settings on the cluster itself in its favor. A file with a DNS name therefore needs Envoy 1.33 or later:DnsClusterfirst appears in Envoy 1.33.0 (itsdns_cluster.protois absent at v1.32.13). Measured withenvoy --mode validatein the official images, a file whose one service has a DNS name, with or withoutdns.resolver, loads in Envoy 1.33.14 and 1.40.2, and Envoy 1.32.13 refuses it withcould not find @type 'type.googleapis.com/envoy.extensions.clusters.dns.v3.DnsCluster'; 1.33.0 to 1.33.13 were not measured. proxyfile 2.1.0 wrote the DNS settings on the cluster itself, a form all three load. Separately, Envoy 1.33.14 refusesbalance: hash(no such field: 'hash_policy'); the lowest version that takes it was not measured. - The client's address is
forwardedwithouttlsandconnectionwith it, whenclient_addressis not written. Withforwarded(use_remote_address: false) a proxy stands in front:X-Forwarded-Forpasses as it came,X-Forwarded-Protois kept when present, and with no trusted hops Envoy takes the lastX-Forwarded-Forentry, the one the proxy in front appended, as the client's address. Withconnection(use_remote_address: true) the client's address is the peer of the connection, which Envoy appends toX-Forwarded-For, andX-Forwarded-Protois set from the connection. The listener says when to write which. - A browser origin that is not admitted gets
403with the bodyInvalid CORS request, the answer a Spring service gives for a refused origin. Changing it needs a key that does not exist yet. - Every response carries
x-request-id, the client's own when it sent one, so a caller can quote the id of a failed call. It is therequest_idof the request log. Withclient_address: connection, Envoy replaces a client's own id on a request it counts as external. - The service's own
Serverheader passes through, and Envoy adds none of its own. The router adds nox-envoy-*header to a request it sends a service or to an answer. Withclient_address: connection, Envoy itself addsx-envoy-external-addressto the request (The listener). Withauth.ask, Envoy's own client for the check addsx-envoy-upstream-service-timeto the check's answer, and a denial passes the check's headers on, so the gateway removes that header from every answer, a service's own copy included; the check's other headers still reach the client. That client also addsx-envoy-internal: trueandx-envoy-expected-rq-timeout-msto the request the check receives, which the generated file does not remove (auth). Measured on Envoy 1.40.2. Vary: Originon every response, added to aVarythe service sent, never replacing it.- Every request's path is normalised before a route is picked.
normalize_path: true,merge_slashes: trueandpath_with_escaped_slashes_action: UNESCAPE_AND_FORWARDare always written: dot segments are resolved, repeated slashes merged, and%2F, a backslash and%5Cread as/, so the route, a rate limit, the token, the check and the service all read the path the service receives. A;parameter on a name and the case of letters are kept as sent, and a;parameter on a dot segment written with dots is dropped with the segment resolved. Measured on Envoy 1.40.2 (routes, A route withauth: off). Envoy drops that parameter itself from 1.40.0, and from 1.36.10, 1.37.6, 1.38.4 and 1.39.1 on the older release lines, as their release notes say, while the runtime settingenvoy.reloadable_features.strip_dotdot_segments_with_parametersis on, its default. On an older Envoy, or with the setting off, the segment stays in the path and is answered400by the rule below: measured on Envoy 1.33.14, and on 1.40.2 with the setting off. - A path that still holds a dot segment with a
;parameter, the;written or escaped once, is answered400. The first route of every virtual host,refused:dot-segment-with-parameter, takes a path that holds/.;,/..;,/.%3Bor/..%3Bafter normalisation, with the hex in either case, so no route of the proxyfile takes it and it reaches no service. Envoy keeps%3Bescaped as sent, so a hop between the gateway and the service that decodes it once would hand the service the..;that A route withauth: offdescribes. A;escaped twice (%253B), a;on any other segment and the query reach the service as sent. Measured on Envoy 1.40.2 and 1.33.14. The route does not turnauthoff, so the token filter and the check still run before its400. - WebSocket is the one upgrade passed on. Envoy answers any other
Upgradeto a route with403and an empty body. - A service that cannot be reached answers
502with an empty body, where Envoy's own answer is a503or a502with a body that describes the failure. - A Connect call over a rate limit gets the Connect error
resource_exhausted, a429with a JSON body, where Envoy's own429is plain text, which a Connect client reads asunavailable. It is written with arate_limit(Rate limits). - A check's 2xx other than
200is answered403, withauth.ask. Only200lets a request through, so the client never receives a success for a request that did not reach the service (auth). - Headers are removed early. Everything in
remove_from_clients, and withauth.askthe headerx-envoy-auth-failure-mode-allowed, is removed before routing and before any filter. Withauth.ask, the gateway also removes from clients the two question headers and every header the check may set (each name ofauth.accept), and withauth.jwtevery header a verified token sets (each header ofauth.jwt.claims), whether or notremove_from_clientslists them, because a client must not be able to forge what the gateway asks the check, what the check says or what the token says. Withtracing(orenvoy.tracing),x-envoy-downstream-service-clusterandx-envoy-downstream-service-nodeare removed after those, and withotel,x-envoy-decorator-operationlast, which a client could otherwise use to rename the span; each unless an entry before it covers it. - No
tracingand noenvoy.tracing: no tracer. Tracing says what the key writes. - No
auth.send_request: the check sees the path ofaskonly. What the check is told says what the key adds. - No
auth.jwt: no token is verified at the proxy. Tokens says what the key adds. - Retries happen only on
connect-failureandreset-before-request, and go to a backend the request has not tried yet when the service has one. The retry policy carries Envoy'sprevious_hostspredicate withhost_selection_retry_max_attempts: 20: a pick of a backend already tried is made again, at most 20 times, and then the retry goes to the last backend picked, so a service with one backend is still retried on it. The count is 20 because a new pick can be a backend already tried:least_requestsandrandomdraw each pick anew, andhashtakes the next entry along its ring, the same entries for a value every time. Measured on Envoy 1.40.2 with two backends and one refusing connections: withrandom, each count about halved the share of retries that reached the refusing backend again, from 24.8% at 1 to 0.19% at 7 and at 8 (1000 requests for each count); withhashon a header, 87 of 200 values hashed to the refusing backend, and 56, 27, 15, 5 and 3 of them still failed at counts 1 to 5, none at 6. At 6, the smallest count at which 200 requests in a row were all answered200with everybalance,randomstill failed 3 of 1000. At 20, by that halving, fewer than one in a million fail withrandom, and 5000 requests with eachbalancewere all answered by the other backend. Without the predicate a retry picked its backend as the first try did: withleast_requests, 53 of 200 requests were answered502, and withhash, every request whose hash chose the refusing backend. Round robin takes the other of two backends next, with or without it. - The overload manager checks every 0.25 seconds. It exists when
envoy.heaporlimits.connectionsis written. - The Connect bridge. Each route of the rpc entry turns a Connect call into gRPC for the service's gRPC port, and
the answer back into Connect. Envoy's bridge still writes the HTTP status of an older Connect error-code table for
four codes, so a small Lua filter sets the current status:
canceled499,deadline_exceeded504,failed_precondition400 andunimplemented501. Both filters are off for every other route, and neither is written whenenvoy.connect_bridgeisfalse. - Route metadata. With
auth.ask, a plain route carries an empty action underenvoy.namespace, and an RPC route carries its method's action. A route withauth: offcarries none. The auth-unavailable log line reads it. A limited route also carries its bucket under<envoy.namespace>.rate_limit, which the rate limit filter reads, so a route withauth: offand a limit carries its bucket alone. - Three kinds of JSON log line on standard output. The request log has the fields
time,route,host,method,protocol,status,flags,details,duration_ms,upstream_ms,bytes_in,bytes_out,upstreamandrequest_id, and withauth.askalsoauthz_us, how long the check took (nullwhen none ran). The upstream failure line (event: gateway_upstream_failure) is written for each request an upstream failed. The auth-unavailable line (event: gateway_auth_unavailable) is written withauth.askonly. No log line holds a path, query, address, user agent or referrer, because paths can carry links and tokens. Withlog, the request log writes every response at or abovestatus_from, every response with a response flag, andsampleof the rest, chosen by the first eight hex digits ofx-request-id. - The order of the filters: set metadata (with
auth.ask), header mutation, the RBAC refusal of a foreign browser origin, CORS, the rate limit filter (only when a route or the rpc entry has arate_limit), the token filter (withauth.jwt), the auth check (withauth.ask), the Lua status filter and the Connect bridge (with an rpc entry, unlessenvoy.connect_bridgeisfalse), and the router. A foreign origin and a request over a rate limit are refused before a token is verified or the check could be called, and a token is verified before the check is asked.
Fixed names
These names never follow envoy.namespace or any other key, because other programs read them. A tool that changes a
runtime value, for example, looks it up by its key.
| Name | What it is |
|---|---|
public |
The listener, its stat_prefix and the route table. |
refused:dot-segment-with-parameter |
The first route of every virtual host, which answers 400 to a path that still holds /.;, /..;, /.%3B or /..%3B (the hex in either case) after normalisation. The request log writes it as route. No route of the file can take the name, because a route name holds no colon. |
gateway.ext_authz.enabled |
The runtime key that switches the auth check, written with auth.ask. Its default comes from auth.enabled. |
gateway.request_log.min_status |
The runtime key for the lowest status that is always logged, written with log. Its default comes from log.status_from. |
gateway.request_log.sample |
The runtime key for the share of other requests that is logged, written with log. Its default comes from log.sample. |
gateway.local_reply.origin_refused_status |
The runtime key for the status the Invalid CORS request answer is matched on. Its default is 403. |
gateway.local_reply.rate_limited_status |
The runtime key for the status the Connect answer to a call over a rate limit is matched on, written with a rate_limit. Its default is 429. |
rate_limit |
The rate limit filter's stat_prefix, written with a rate_limit. |
otel_collector |
The cluster of the tracing endpoint, written with the otel provider. |
jwks |
The cluster of the keys URL's host, written when auth.jwt.keys is an https URL. |
browser-origins |
The one RBAC policy of each virtual host. |
x-gateway-action, x-gateway-reports |
The question headers of an RPC route, read by the auth check. |
x-gateway-timeout-ms |
The check's deadline in milliseconds. |
One line of the generated file is meant for a tool to switch by editing the file as text: the default of the auth check.
It stays on one line in flow style for that purpose. It reads {numerator: 100, denominator: HUNDRED} when the check is
on and {numerator: 0, denominator: HUNDRED} when it is off:
default_value: {numerator: 100, denominator: HUNDRED}proxyfile check fails on an edited file, as it does on any edit, so check the file before a tool edits it. To change
the setting for good, change auth.enabled and render again.