services
Backend pools that routes send traffic to.
services.<name>.backends
Section titled “services.<name>.backends”Type: list of object
Backend servers. Set this or split.
services.<name>.backends[].address
Section titled “services.<name>.backends[].address”Type: BackendAddress · Required
host:port, [ipv6]:port or unix:///path.sock.
services.<name>.backends[].weight
Section titled “services.<name>.backends[].weight”Type: integer · Default: 1
Relative share of traffic.
services.<name>.health planned for v0.4
Section titled “services.<name>.health ”Type: object
Active and passive health checks.
services.<name>.health.active
Section titled “services.<name>.health.active”Type: object
Periodic probes.
services.<name>.health.active.expected_status
Section titled “services.<name>.health.active.expected_status”Type: string · Default: 200-399
Accepted status codes, e.g. 200 or 200-399.
services.<name>.health.active.healthy
Section titled “services.<name>.health.active.healthy”Type: integer · Default: 2
Consecutive successes before a backend is healthy.
services.<name>.health.active.interval
Section titled “services.<name>.health.active.interval”Type: Duration · Default: 10s
Time between probes.
services.<name>.health.active.path
Section titled “services.<name>.health.active.path”Type: string · Default: /
Path to request.
services.<name>.health.active.port
Section titled “services.<name>.health.active.port”Type: integer
Probe this port instead of the backend’s.
services.<name>.health.active.timeout
Section titled “services.<name>.health.active.timeout”Type: Duration · Default: 2s
Probe timeout.
services.<name>.health.active.unhealthy
Section titled “services.<name>.health.active.unhealthy”Type: integer · Default: 3
Consecutive failures before a backend is unhealthy.
services.<name>.health.passive
Section titled “services.<name>.health.passive”Type: object
Ejection based on observed failures.
services.<name>.health.passive.ejection
Section titled “services.<name>.health.passive.ejection”Type: Duration · Default: 30s
How long an ejected backend stays out before it is tried again.
services.<name>.health.passive.failures
Section titled “services.<name>.health.passive.failures”Type: integer · Default: 5
Failures within window that eject a backend.
services.<name>.health.passive.window
Section titled “services.<name>.health.passive.window”Type: Duration · Default: 30s
Sliding window for counting failures.
services.<name>.load_balancer
Section titled “services.<name>.load_balancer”Type: object · Default: {"hash_on":null,"policy":"round_robin"}
How a backend is chosen for each request.
services.<name>.load_balancer.hash_on
Section titled “services.<name>.load_balancer.hash_on”Type: string
Header or cookie name for header_hash and cookie_hash.
services.<name>.load_balancer.policy
Section titled “services.<name>.load_balancer.policy”Type: round_robin · random · least_conn · least_requests · p2c · ip_hash · header_hash · cookie_hash · Default: round_robin
Selection policy.
round_robin: Weighted round-robin.random: Weighted random.least_conn: Fewest open connections.least_requests: Fewest in-flight requests.p2c: Power of two random choices.ip_hash: Consistent hash of the client IP.header_hash: Consistent hash of a request header (hash_on).cookie_hash: Consistent hash of a cookie (hash_on).
services.<name>.pass_host_header
Section titled “services.<name>.pass_host_header”Type: boolean · Default: true
Forward the client’s Host header (otherwise the backend address is used).
services.<name>.retries planned for v0.4
Section titled “services.<name>.retries ”Type: object
Retries of failed requests (transport failures only, see ADR-0010).
services.<name>.retries.attempts
Section titled “services.<name>.retries.attempts”Type: integer · Default: 2
Additional attempts after the first.
services.<name>.retries.budget_percent
Section titled “services.<name>.retries.budget_percent”Type: integer · Default: 20
Maximum share of retries relative to requests, in percent, to avoid retry storms.
services.<name>.retries.on
Section titled “services.<name>.retries.on”Type: list of connect · reset · timeout · Default: ["connect"]
Failures that are retried.
services.<name>.retries.retry_non_idempotent
Section titled “services.<name>.retries.retry_non_idempotent”Type: boolean · Default: false
Also retry non-idempotent methods such as POST. Only safe if backends are idempotent.
services.<name>.scheme
Section titled “services.<name>.scheme”Type: http · https · h2c · Default: http
Protocol spoken to the backends. gRPC uses h2c (cleartext) or https.
http: HTTP/1.1 in cleartext.https: HTTP/1.1 or HTTP/2 over TLS.h2c: HTTP/2 in cleartext (gRPC without TLS).
services.<name>.split planned for v0.4
Section titled “services.<name>.split ”Type: list of object
Weighted traffic split over other services (canary, blue/green). Set this or backends.
services.<name>.split[].service
Section titled “services.<name>.split[].service”Type: string · Required
Another service (name or name@provider).
services.<name>.split[].weight
Section titled “services.<name>.split[].weight”Type: integer · Required
Relative share of traffic.
services.<name>.sticky planned for v0.4
Section titled “services.<name>.sticky ”Type: object
Session affinity with a cookie.
services.<name>.sticky.cookie
Section titled “services.<name>.sticky.cookie”Type: object · Required
Affinity cookie.
services.<name>.sticky.cookie.http_only
Section titled “services.<name>.sticky.cookie.http_only”Type: boolean · Default: true
Hide from JavaScript.
services.<name>.sticky.cookie.max_age
Section titled “services.<name>.sticky.cookie.max_age”Type: Duration
Lifetime; a session cookie when omitted.
services.<name>.sticky.cookie.name
Section titled “services.<name>.sticky.cookie.name”Type: string · Required
Cookie name.
services.<name>.sticky.cookie.same_site
Section titled “services.<name>.sticky.cookie.same_site”Type: lax · strict · none · Default: lax
SameSite attribute.
lax:Lax.strict:Strict.none:None(requiressecure).
services.<name>.sticky.cookie.secure
Section titled “services.<name>.sticky.cookie.secure”Type: boolean · Default: true
Send only over HTTPS.
services.<name>.timeouts
Section titled “services.<name>.timeouts”Type: object · Default: {"connect":"5s","idle":"1m30s","read":"1m","write":"1m"}
Upstream timeouts.
services.<name>.timeouts.connect
Section titled “services.<name>.timeouts.connect”Type: Duration · Default: 5s
Establishing a connection.
services.<name>.timeouts.idle
Section titled “services.<name>.timeouts.idle”Type: Duration · Default: 1m30s
Keeping an idle pooled connection.
services.<name>.timeouts.read
Section titled “services.<name>.timeouts.read”Type: Duration · Default: 1m
Waiting for response data.
services.<name>.timeouts.write
Section titled “services.<name>.timeouts.write”Type: Duration · Default: 1m
Sending request data.
services.<name>.tls
Section titled “services.<name>.tls”Type: object
TLS to the backends when scheme is https.
services.<name>.tls.ca_file
Section titled “services.<name>.tls.ca_file”Type: string
CA bundle used instead of the system roots.
services.<name>.tls.cert_file
Section titled “services.<name>.tls.cert_file”Type: string
Client certificate for upstream mTLS.
services.<name>.tls.key_file
Section titled “services.<name>.tls.key_file”Type: string
Client key for upstream mTLS.
services.<name>.tls.server_name
Section titled “services.<name>.tls.server_name”Type: string
SNI and verification name, when it differs from the backend host.
services.<name>.tls.verify
Section titled “services.<name>.tls.verify”Type: boolean · Default: true
Verify the backend certificate and host name.