The format
A proxyfile describes one gateway in keys, in YAML or in HOCON. This page holds a file with every key but the few it names, the forms of sizes, times and percentages, the rules that compare keys with each other, the two JSON files of 1.0, which keys a 1.x file moves, what 2.1 changes for a 2.0 file and what 2.2 changes for a 2.1 file.
examples/full/yaml/proxyfile.yaml holds every key a proxyfile can have, with invented values, except rpc.proto,
envoy.tracing, the xray provider, hash.client and the nginx and haproxy blocks, which take no key in this
version. Other examples write the first four and what the full example writes one way only:
examples/partial/proto-methods writes rpc.proto; examples/tracing the xray provider at tracing and, in
envoy-tracing/, at envoy.tracing, where it gives the same envoy.yaml; examples/balanced and examples/dns the
other ways to give a service its backends, hash.client among them; examples/otel a tracing endpoint by name; and
examples/jwt a keys file and a route without the token check. examples/partial gives its methods three ways, each
in a folder of its own: yaml/proxyfile.yaml with --rpc-methods ../methods.json, hocon/Proxyfile through
include required("../rpc-methods.conf"), and proto-methods/Proxyfile through rpc.proto and the .proto files
under proto/. examples/grpc/yaml/proxyfile.yaml turns envoy.connect_bridge off. Only listen, services,
origins and routes are required. The rest is left out when you do not need it.
# yaml-language-server: $schema=../../../schema/proxyfile.schema.json
# Every key but rpc.proto, envoy.tracing, the xray provider, hash.client, nginx and haproxy, with invented values.
listen: 10000
admin: 9901
tls:
certificate: /etc/gateway/tls/certificate.pem
key: /etc/gateway/tls/key.pem
clients: {ca: /etc/gateway/tls/clients-ca.pem}
client_address: connection
limits:
connections: 4096
request_headers: {size: 96KiB, count: 150}
timeouts:
request: none
idle: 90s
upstream_idle: 45s
services:
shop:
http: 8080
grpc: 8081
addresses: ["10.0.1.11", "10.0.1.12"]
balance: least_requests
health: {path: /healthz, grpc: true, interval: 10s, timeout: 1s, healthy: 2, unhealthy: 3}
accounts: {grpc: 7070, http: 7070, host_header: "127.0.0.1:7070"}
catalog: {http: 8090, address: catalog.internal.example, balance: hash, hash: {header: x-session-id}}
dns: {resolver: "10.0.0.2:53"}
auth:
ask: accounts /auth/check
timeout: 1500ms
enabled: true
when_unavailable: allow
only_with_header: authorization
send: [authorization, x-country]
accept: [x-user-*, x-tier-*]
send_request: true
jwt:
issuer: https://login.example.com
audiences: [api.example.com, admin.example.com]
keys: https://login.example.com/.well-known/jwks.json
ca: /etc/gateway/jwt/ca.pem
header: x-access-token
optional: true
claims: {x-subject: sub, x-roles: realm.roles}
remove_from_clients: [x-user-*, x-client-*, x-tier-*, x-gateway-*]
cors:
allow_methods: "*"
allow_headers: "*"
expose_headers: "Content-Disposition,X-Request-Id"
max_age: "600"
origins:
live:
hosts: [api.example.com, api.example.org]
origins: ["https://example.com", "https://www.example.com"]
patterns: ["https://*.example.com"]
test:
hosts: [api.test.example.com]
origins: ["http://localhost:3000", "https://test.example.com"]
patterns: ["https://*.test.example.com"]
local:
hosts: [127.0.0.1, localhost]
origins: []
patterns: ["http://*.example.com:*", "http://localhost:*"]
routes:
- {name: accounts-events, pattern: "^/events/[a-z0-9-]+$", to: accounts, auth: off}
- rpc:
retries: 1
rate_limit: {requests: 100, per: 1s, by: all}
to:
example.shop.*: {service: shop, name: shop}
"*": accounts
- {name: accounts-webhooks, path: /api/webhooks, method: POST, to: accounts, rewrite: /hooks/payments, auth: off}
- {name: catalog, prefix: /catalog/, to: catalog, rate_limit: {requests: 20, per: 1s, burst: 10, by: client}}
- {name: shop, prefix: /, to: shop, retries: 1}
rpc:
methods:
- {service: example.shop.v1.CartService, method: GetCart, action: browse}
- {service: example.accounts.v1.ProfileService, method: GetProfile}
- {service: example.shop.v1.CartService, method: AddItem, action: buy, reports: [browse]}
log: {status_from: 400, sample: 1%}
tracing:
provider:
otel:
endpoint: 10.0.3.40:4317
service: example-gateway
sample: {rate: 10%}
tags:
environment: {env: APP_ENVIRONMENT, default: local}
request_id: {header: x-request-id}
path_in_url: true
envoy:
namespace: example.gateway
heap: 256MiB
connect_bridge: trueThe first line points an editor at the schema in this repository. In your own files, use the URL under Editors.
The examples on these pages are YAML, whose file name ends in .yaml or .yml; The HOCON form gives the
other names and the same keys in HOCON. An unknown key anywhere is a problem, and the message lists the keys that are
known at that place.
No key or value may hold a control character other than tab: NUL, a newline, a carriage return, any other character
from U+0001 to U+001F but tab, or U+007F. Written into the generated file as it is, such a character would break the
header value, the path or the name that holds it. It is written with an escape in quotes, such as "a\nb", or as a
line break inside a YAML block or a HOCON """ string; a YAML block keeps the line break at its end unless it is
written |- or >-. Each such key or value is one problem, at its place, which names the first such character:
the value "a\nb" contains a newline; no key or value may hold a control character other than tab. The origins file,
the methods file and the action and reports read from .proto files follow the same rule.
Sizes, times and percentages
Sizes are a whole number with KiB, MiB or GiB, such as 192MiB. Times are a whole number with ms, s, m or
h, such as 125s, and at most 9223372035s (about 292 years), the largest whole number of seconds below the limit
Envoy sets on a duration. auth.timeout has a lower limit, which its row in auth gives. A percentage is a
whole number from 0 to 100 with a %.
Rules across keys
A proxyfile also has these rules, each reported with the file and where the problem is, a line in YAML and a key path in HOCON:
listenandadminare not the same port.- At least one service is declared, and each service has at least one port.
- A route,
auth.askor an RPC mapping names a service that is declared and has a port of the protocol it needs:httpfor a route and forauth.ask,grpcfor an RPC mapping. - A service writes
addressoraddresses, not both, andaddresseslists two or more addresses, none twice. hashis written exactly whenbalanceishash.healthwritespathorgrpc;pathneeds anhttpport andgrpcagrpcport;health.timeoutis shorter thanhealth.interval, the defaults included.authwritesask,jwtor both.timeout,enabledandwhen_unavailableare written withaskand only with it, andonly_with_header,send,acceptandsend_requestneed it.auth.jwt.caneeds a URL inauth.jwt.keys. A header ofauth.jwt.claimsis not one thatauth.sendorauth.acceptnames.auth.jwt.headeris notcookie, and the header that carries the token is neither a header ofauth.jwt.claimsnor one aremove_from_clientsentry covers.auth: offon a route needs anauthkey.corsis not written whenoriginsnames a file, because the generator takes the CORS settings from that file and would ignore this key.- The RPC methods come from one place:
rpc.methods,rpc.protoor--rpc-methods. They need an rpc entry inroutes, and the rpc entry needs them. tracingandenvoy.tracing, its old place, are not both written.
The origins file and the methods file
Since 1.1 both can be written in the proxyfile: the environments under origins, the CORS settings under cors, and
the methods under rpc.methods. From 1.3 the methods can also be read from the .proto files, with rpc.proto. A
HOCON proxyfile that wants a separate file uses include, as examples/partial/hocon/Proxyfile does for its methods.
The 1.0 way is still accepted in 2.x, with the same rules: origins: <file> names a JSON origins file, and
--rpc-methods <file> a JSON methods file. Any two of rpc.methods, rpc.proto and --rpc-methods together are
refused, because exactly one gives the methods. cors in the proxyfile is refused too when origins names a file.
The two files are JSON. They are read with the YAML reader, so a problem in either names its line and column, and a
syntax error its line. A slash escaped as \/, which JSON allows and some writers produce, is read as /.
origins describes the origins file, and rpc the methods file.
From 1.x to 2.0
proxyfile 2.0 moves the three keys only Envoy reads into the envoy block. A 1.x file is refused with one
problem for each key still at its 1.x place, and each problem names where the key goes:
| In 1.x | In 2.0 |
|---|---|
namespace |
envoy.namespace |
limits.heap |
envoy.heap |
tracing |
envoy.tracing |
From 2.1 a 1.x file's tracing is read again where 1.x wrote it, as the tracing key, so only
namespace and limits.heap still move.
Every other key stays where it was, and in 2.0 a file with the three keys moved renders the same bytes as in 1.x. The
Connect bridge on RPC routes, which 1.x always wrote, is now envoy.connect_bridge, true when not written, so a 1.x
file needs no line for it.
From 2.0 to 2.1
Render every file again after the upgrade, because every generated configuration changes. The proxy now normalises
each request's path before it picks a route, with three lines of the listener: normalize_path: true,
merge_slashes: true and path_with_escaped_slashes_action: UNESCAPE_AND_FORWARD, where 2.0 wrote the first two as
false. So a service receives /b for /a/../b, /a for //a and a/b for a%2Fb
(A route with auth: off says why). Each virtual host also gains a first route, three
lines, that answers 400 to a path that still holds /.; or /..; after normalisation. Until a file is rendered
again, proxyfile check reports its 2.0 output as different.
With auth, the listener also gains one local reply mapper, seven lines: a check that answers a 2xx other than 200,
such as 201, 202 or 204, now gives the client 403. 2.0 passed that 2xx on to the client, a success for a request
that never reached the service (A check that answers another 2xx).
tracing is a key at the top again. envoy.tracing, where 2.0 read it, stays its old place in every 2.x
release, with the xray provider only. A file that writes both is refused, and moving the block from envoy.tracing
to tracing changes no byte. A 1.x file's tracing is read again where 1.x wrote it.
No 2.0 file is refused. auth takes jwt, with or without ask, and timeout, enabled and
when_unavailable stay required with ask, as in 2.0.
The keys 2.1 adds:
services.<name>.addresses: several backends for one service.- A DNS name in
address: backends the proxy looks up while it runs. balance: how requests are spread over the backends.hash: whatbalance: hashhashes, a header or the client's address.health: checks that take a failing backend out of the pool.dns: the name server the proxy asks.tls: HTTPS on the public listener, and withclientsmutual TLS.client_address: which address counts as the client's.rate_limit: how many requests a route or the rpc entry admits.tracingwithotel: spans sent to an OpenTelemetry collector.auth.send_request: the check learns which request it is asked about.auth.jwt: the proxy verifies a signed token on the request itself.
From 2.1 to 2.2
Render every Envoy file again after the upgrade, because every generated configuration changes: the first route of
each virtual host, refused:dot-segment-with-parameter, also answers 400 to a path that still holds /.%3B or
/..%3B after normalisation, with the hex in either case (Defaults). Until a file is rendered again,
proxyfile check reports its 2.1 output as different.
The Envoy output also changes in three ways:
- A cluster that looks a DNS name up, for a service's address, the tracing endpoint or the keys URL's host, is Envoy's
DnsCluster, so a file with a DNS name needs Envoy 1.33 or later. 2.1 wrote the DNS settings on the cluster itself (Defaults). - A retry goes to a backend the request has not tried yet when the service has one (
routes). - With
auth.ask, no answer carriesx-envoy-upstream-service-time, a service's own copy included (Defaults).
A file 2.1 rendered is refused when a key or a value holds a control character other than tab, as this page says
above, such as the line break a YAML | block keeps at its end (write |-); when an rpc.proto root lies inside
another or names one directory twice (rpc); or when a bare ! tag
stands on the line after an anchor. Each problem names its place.
2.2 adds no key. proxyfile render --target nginx and --target haproxy write nginx's and HAProxy's files
(nginx, HAProxy).