YAML configuration parameter reference

This reference covers all 159 YAML parameters and containers in BonVoyage configuration schema version 1. The tables are generated from the release-matched completion metadata and reviewed field-help catalog. The examples come from the compiler-backed snippet catalog.

Start with a complete document

Use the Docker quickstart and the baseline below before adding optional transport, policy, or routing fragments.

How to read the paths

Paths use RFC 6901-style notation. A * represents one array item, so /listeners/*/port means the port field on every object in the top-level listeners array.

Required means the field is directly required by its containing object. Optional fields can still become conditionally required by another selection. Those relationships are listed under cross-field rules. Exact regular expressions and structural rules remain available in config/schemas/bonvoyage-config.schema.json. The authoritative Go snapshot compiler performs semantic validation, defaults, reference checks, and supported-feature checks that a field table cannot replace.

Complete baseline example

Local gateway baseline. Start a complete local listener, fixed response, proxied route, upstream cluster and bounded runtime profile.

config/examples/local.yaml:

server:
  node_id: bonvoyage-local
  admin_addr: 127.0.0.1:9901
  metrics_addr: 127.0.0.1:9090
snapshot:
  schema_version: 1
  snapshot_id: local-bootstrap
  generation: 1
  minimum_dataplane_version: 0.2.0
listeners:
  - name: http
    address: 0.0.0.0
    port: 8080
    protocol: http1
    virtual_hosts:
      - default
virtual_hosts:
  - name: default
    domains:
      - '*'
    routes:
      - name: local-response
        match:
          path_exact: /bonvoyage/ready
        fixed_response:
          status_code: 200
          body: |
            ready
          content_type: text/plain
      - name: default-route
        match:
          path_prefix: /
        cluster: local-upstream
clusters:
  - name: local-upstream
    load_balancing_policy: round_robin
    connect_timeout_ms: 1000
    max_connections_per_shard: 128
    max_pending_requests_per_shard: 256
    endpoints:
      - name: upstream-1
        address: upstream
        port: 8081
        weight: 1
runtime_limits:
  max_downstream_connections_per_shard: 16384
  max_request_header_bytes: 32768
  max_request_body_bytes: 10485760
  max_upstream_response_header_bytes: 32768
  max_upstream_chunk_metadata_bytes: 32768
  request_timeout_ms: 15000
  downstream_idle_timeout_ms: 60000

Validate the complete file before applying it:

go run ./control-plane/cmd/bonvoyage-config validate \
  --input config/examples/local.yaml

Feature examples

Each fragment below names its insertion path. Merge it into a complete document, then validate the whole document. Secret-reference fields accept deployment filenames such as server-key.pem; never paste a private key, API key, JWKS document, or certificate body into YAML.

Upstream TLS and mTLS

Add server identity verification and an optional client certificate to one upstream cluster.

Place this fragment at /clusters/* using merge-object semantics:

upstream_tls:
  server_name: backend.internal.example.com
  trust_bundle_secret: backend-ca.pem
  certificate_chain_secret: gateway-client.pem
  private_key_secret: gateway-client-key.pem

Downstream TLS

Enable a listener certificate and private-key reference using deployment-secret filenames.

Place this fragment at /listeners/* using merge-object semantics:

downstream_tls:
  certificate_chain_secret: server-chain.pem
  private_key_secret: server-key.pem

API-key admission

Require a named request header whose value is checked against a deployment-secret credential file.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

api_key_auth:
  header_name: X-API-Key
  credentials_secret: phase3-api-keys.txt

CORS policy

Add bounded browser-origin, method, header, credential and preflight-cache rules to one route.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

cors:
  allowed_origins:
    - https://app.example.com
    - http://localhost:3000
  allowed_methods:
    - GET
  allowed_headers:
    - Authorization
    - Content-Type
    - X-Request-Id
  exposed_headers:
    - X-Request-Id
    - X-Trace-Id
  allow_credentials: true
  max_age_seconds: 600

Fixed-response route

Append a route that returns a local status, body and content type without contacting an upstream.

Place this fragment at /virtual_hosts/*/routes using append-array-item semantics:

- name: local-response
  match:
    path_exact: /bonvoyage/ready
  fixed_response:
    status_code: 200
    body: |
      ready
    content_type: text/plain

Header transformations

Set, append or remove bounded request and response headers on one route.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

header_transformations:
  request:
    - operation: set
      name: x-request-set
      value: gateway-set
    - operation: append
      name: x-request-append
      value: gateway-append
    - operation: remove
      name: x-request-remove
    - operation: set
      name: x-request-added
      value: gateway-added
  response:
    - operation: set
      name: x-response-set
      value: gateway-set
    - operation: append
      name: x-response-append
      value: gateway-append
    - operation: remove
      name: x-response-remove
    - operation: set
      name: x-response-added
      value: gateway-added

JWT admission

Validate JWT signature, issuer, audience, scopes, claims and bounded verification admission on one route.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

jwt_auth:
  jwks_secret: phase3-jwks.json
  issuer: https://issuer.example.test
  audience: payments-api
  required_type: at+jwt
  algorithms:
    - RS256
  clock_skew_seconds: 5
  max_token_lifetime_seconds: 300
  required_scopes:
    - payments:read
  required_claims:
    - name: tenant
      exact: tenant-a
  verification_rate_limit:
    capacity: 1000
    refill_tokens_per_second: 1000

Local route rate limit

Add a shard-local token bucket with explicit capacity and refill rate to one route.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

local_rate_limit:
  capacity: 2
  refill_tokens_per_second: 1

Request-content policy

Constrain request body size and accepted media types before forwarding upstream.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

request_content:
  max_body_bytes: 8
  allowed_content_types:
    - application/json
    - application/problem+json

Upstream request rewrite

Rewrite the upstream authority and path prefix for one matched route.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

rewrite:
  host: orders.internal.test
  port: 9443
  path_prefix: /v2/

Static redirect

Return a bounded redirect status and location components without contacting an upstream.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

redirect:
  status_code: 307
  path: /v2/orders
  query: source=legacy

Proxied upstream route

Append a prefix route that forwards matching requests to a named cluster.

Place this fragment at /virtual_hosts/*/routes using append-array-item semantics:

- name: default-route
  match:
    path_prefix: /
  cluster: local-upstream

Weighted upstream clusters

Distribute one route deterministically across named clusters using positive integer weights.

Place this fragment at /virtual_hosts/*/routes/* using merge-object semantics:

weighted_clusters:
  - cluster: stable
    weight: 3
  - cluster: canary
    weight: 1

Cross-field rules

• A route match selects exactly one of path_exact, path_prefix, or safe_regex.
• Every route selects exactly one action: cluster, weighted_clusters, fixed_response, or redirect.
• api_key_auth and jwt_auth are mutually exclusive on one route.
• Header transformations and rewrites require an upstream cluster action. WebSocket forwarding also requires a cluster action and max_concurrent_requests_per_shard.
• Downstream mTLS requires require_client_certificate: true and trust_bundle_secret. Without client-certificate enforcement, a downstream trust bundle is rejected.
• An upstream certificate chain and private key must be configured together. HTTP/2 upstream clusters require upstream_tls; max_http2_streams_per_connection is valid only for HTTP/2.
• A header or query matcher chooses exactly one of exact or present.
• CORS chooses either allow_any_origin: true or an allowed_origins list. Source-IP policy requires at least one allow or deny CIDR list. Request-content policy requires at least one bound.
• A remove header mutation carries no value; set and append require one.
• Redirect scheme and host are paired; port requires both. A rewrite cannot set both path and path_prefix.
• Schema-recognized syntax is not automatically a supported runtime feature. For example, the first OSS candidate supports downstream HTTP/1.1 and HTTP/2; selecting http3 is rejected by semantic validation.

Run offline validation after every edit. Use configuration diagnostics to interpret a rejection and supported capabilities before relying on a protocol or operating mode.

Parameter catalog

Server identity and local management

These fields identify one gateway process and bind its local administration and metrics endpoints.

YAML path	Parameter	Type	Direct presence	Constraints	Meaning
/server	Server identity	object	Required	None at this structural level	Local node identity and administrative bind addresses for this gateway process.
/server/admin_addr	Admin address	string	Required	at least 1 character	The local address used by the gateway administrative endpoint.
/server/metrics_addr	Metrics address	string	Required	at least 1 character	The local address used to expose Prometheus metrics.
/server/node_id	Node ID	string	Required	at least 1 character	The stable identity reported by this gateway node to management and observability surfaces.

Snapshot identity

These fields version the desired state compiled into one immutable runtime snapshot.

YAML path	Parameter	Type	Direct presence	Constraints	Meaning
/snapshot	Snapshot metadata	object	Required	None at this structural level	Version and identity metadata bound to the compiled immutable configuration artifact.
/snapshot/generation	Snapshot generation	integer	Required	minimum 1	A positive operator-controlled generation used to order desired-state revisions.
/snapshot/minimum_dataplane_version	Minimum data-plane version	string	Optional	at least 1 character	The minimum BonVoyage data-plane version declared compatible with this snapshot.
/snapshot/schema_version	Configuration schema version	integer	Required	must be 1	The configuration schema version interpreted by the installed compiler; contract v1 supports version 1.
/snapshot/snapshot_id	Snapshot ID	string	Required	at least 1 character	The stable operator-visible identifier assigned to this desired-state snapshot.

Listeners

Listeners accept downstream connections, select protocol and virtual hosts, and optionally enforce TLS or trusted-proxy boundaries.

YAML path	Parameter	Type	Direct presence	Constraints	Meaning
/listeners	Listeners	array<object>	Required	at least 1 item	The non-empty set of downstream network listeners exposed by the gateway.
/listeners/*/address	Listener address	string	Required	at least 1 character	The local network address on which this listener accepts downstream connections.
/listeners/*/downstream_tls	Downstream TLS	object	Optional	None at this structural level	TLS certificate and optional client-authentication settings for this listener.
/listeners/*/downstream_tls/certificate_chain_secret	Server certificate secret	string	Required	validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing the listener certificate chain.
/listeners/*/downstream_tls/private_key_secret	Server private-key secret	string	Required	validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing the listener private key.
/listeners/*/downstream_tls/require_client_certificate	Require client certificate	boolean	Optional	None at this structural level	Whether the listener requires and verifies a downstream client certificate.
/listeners/*/downstream_tls/trust_bundle_secret	Client trust-bundle secret	string	Optional	validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing authorities trusted for downstream client certificates.
/listeners/*/name	Listener name	string	Required	at least 1 character	The unique stable name of this listener within the snapshot.
/listeners/*/port	Listener port	integer	Required	1 to 65535	The TCP port on which this listener accepts downstream connections.
/listeners/*/protocol	Listener protocol	string	Required	one of http1, http2, http3	The downstream HTTP protocol accepted by this listener.
/listeners/*/trusted_proxy	Trusted proxy policy	object	Optional	None at this structural level	The explicit proxy-network boundary allowed to supply trusted forwarded client identity.
/listeners/*/trusted_proxy/trusted_cidrs	Trusted proxy networks	array<string>	Required	1 to 64 items; items must be unique	The bounded CIDR set whose forwarded client-address metadata may be trusted.
/listeners/*/virtual_hosts	Listener virtual hosts	array<string>	Required	at least 1 item	The names of virtual hosts bound to this listener.

Virtual hosts, routes, and policies

Virtual hosts select domains. Their ordered routes match requests, choose one action, and optionally apply bounded admission or transformation policies.

YAML path	Parameter	Type	Direct presence	Constraints	Meaning
/virtual_hosts	Virtual hosts	array<object>	Required	at least 1 item	The non-empty set of domain-routing tables available to listeners.
/virtual_hosts/*/domains	Virtual-host domains	array<string>	Required	at least 1 item	The domain patterns matched by this virtual host.
/virtual_hosts/*/name	Virtual-host name	string	Required	at least 1 character	The unique stable virtual-host name referenced by listeners.
/virtual_hosts/*/routes	Routes	array<object>	Required	at least 1 item	The ordered non-empty route table evaluated within this virtual host.
/virtual_hosts/*/routes/*/api_key_auth	API-key authentication	object	Optional	None at this structural level	Optional API-key admission policy evaluated before an upstream request is sent.
/virtual_hosts/*/routes/*/api_key_auth/credentials_secret	API-key credentials secret	string	Required	1 to 128 characters; validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing the accepted API-key credential set.
/virtual_hosts/*/routes/*/api_key_auth/header_name	API-key header	string	Optional	1 to 128 characters; validated syntax	The downstream HTTP header from which the API key is read.
/virtual_hosts/*/routes/*/cluster	Route cluster	string	Optional	at least 1 character	The single named upstream cluster selected by this route.
/virtual_hosts/*/routes/*/cors	CORS policy	object	Optional	None at this structural level	Optional cross-origin request and response policy for this route.
/virtual_hosts/*/routes/*/cors/allow_any_origin	Allow any origin	boolean	Optional	None at this structural level	Whether any syntactically valid origin is accepted by this CORS policy.
/virtual_hosts/*/routes/*/cors/allow_credentials	Allow credentials	boolean	Optional	None at this structural level	Whether CORS responses permit downstream credentials under the configured origin policy.
/virtual_hosts/*/routes/*/cors/allowed_headers	Allowed request headers	array<string>	Optional	at most 32 items; items must be unique	The bounded request-header names allowed by CORS preflight handling.
/virtual_hosts/*/routes/*/cors/allowed_methods	Allowed CORS methods	array<string>	Required	1 to 16 items; items must be unique	The HTTP methods allowed by this route’s CORS policy.
/virtual_hosts/*/routes/*/cors/allowed_origins	Allowed origins	array<string>	Optional	1 to 32 items; items must be unique	The explicit origin values accepted when any-origin mode is disabled.
/virtual_hosts/*/routes/*/cors/exposed_headers	Exposed response headers	array<string>	Optional	at most 32 items; items must be unique	The response-header names exposed to browser clients by CORS.
/virtual_hosts/*/routes/*/cors/max_age_seconds	Preflight maximum age	integer	Optional	0 to 86400	The maximum number of seconds a browser may cache a successful CORS preflight.
/virtual_hosts/*/routes/*/fixed_response	Fixed response	object	Optional	None at this structural level	A gateway-generated response action that does not contact an upstream cluster.
/virtual_hosts/*/routes/*/fixed_response/body	Fixed-response body	string	Optional	None at this structural level	The optional response body returned by this fixed-response action.
/virtual_hosts/*/routes/*/fixed_response/content_type	Fixed-response content type	string	Optional	at least 1 character	The optional media type returned with this fixed response.
/virtual_hosts/*/routes/*/fixed_response/status_code	Fixed-response status	integer	Required	200 to 599	The HTTP status code returned by this fixed-response action.
/virtual_hosts/*/routes/*/header_transformations	Header transformations	object	Optional	None at this structural level	Ordered request and response header mutations for an upstream route.
/virtual_hosts/*/routes/*/header_transformations/request	Request header mutations	array<object>	Optional	at most 16 items	The ordered bounded mutations applied before forwarding an upstream request.
/virtual_hosts/*/routes/*/header_transformations/request/*/name	Request header name	string	Required	1 to 128 characters; validated syntax	The normalized HTTP field name targeted by this request mutation.
/virtual_hosts/*/routes/*/header_transformations/request/*/operation	Request mutation operation	string	Required	one of set, append, remove	Whether this request mutation sets, appends, or removes the selected header.
/virtual_hosts/*/routes/*/header_transformations/request/*/value	Request header value	string	Optional	at most 4096 characters	The bounded value used by a request set or append mutation; remove uses no value.
/virtual_hosts/*/routes/*/header_transformations/response	Response header mutations	array<object>	Optional	at most 16 items	The ordered bounded mutations applied before returning an upstream response.
/virtual_hosts/*/routes/*/header_transformations/response/*/name	Response header name	string	Required	1 to 128 characters; validated syntax	The normalized HTTP field name targeted by this response mutation.
/virtual_hosts/*/routes/*/header_transformations/response/*/operation	Response mutation operation	string	Required	one of set, append, remove	Whether this response mutation sets, appends, or removes the selected header.
/virtual_hosts/*/routes/*/header_transformations/response/*/value	Response header value	string	Optional	at most 4096 characters	The bounded value used by a response set or append mutation; remove uses no value.
/virtual_hosts/*/routes/*/jwt_auth	JWT authentication	object	Optional	None at this structural level	Optional signed JWT admission policy evaluated before upstream selection.
/virtual_hosts/*/routes/*/jwt_auth/algorithms	JWT algorithms	array<string>	Required	1 to 3 items; items must be unique	The explicit accepted JWT signature algorithms for this route.
/virtual_hosts/*/routes/*/jwt_auth/audience	JWT audience	string	Required	1 to 256 characters; validated syntax	The required audience claim for tokens admitted by this route.
/virtual_hosts/*/routes/*/jwt_auth/clock_skew_seconds	JWT clock skew	integer	Optional	0 to 300	The bounded time tolerance in seconds applied to JWT time claims.
/virtual_hosts/*/routes/*/jwt_auth/issuer	JWT issuer	string	Required	1 to 1024 characters; validated syntax	The required HTTPS issuer identity for tokens admitted by this route.
/virtual_hosts/*/routes/*/jwt_auth/jwks_secret	JWKS secret	string	Required	1 to 128 characters; validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing the reviewed JSON Web Key Set used for signature verification.
/virtual_hosts/*/routes/*/jwt_auth/max_token_lifetime_seconds	Maximum token lifetime	integer	Required	1 to 86400	The maximum accepted JWT lifetime in seconds.
/virtual_hosts/*/routes/*/jwt_auth/required_claims	Required JWT claims	array<object>	Optional	at most 16 items; items must be unique	The bounded set of additional exact claim matches required for admission.
/virtual_hosts/*/routes/*/jwt_auth/required_claims/*/exact	Required claim value	string	Required	1 to 256 characters; validated syntax	The exact bounded value required for this additional JWT claim.
/virtual_hosts/*/routes/*/jwt_auth/required_claims/*/name	Required claim name	string	Required	1 to 64 characters; validated syntax	The non-reserved JWT claim name evaluated by this exact match.
/virtual_hosts/*/routes/*/jwt_auth/required_scopes	Required JWT scopes	array<string>	Optional	at most 16 items; items must be unique	The bounded set of scopes that an admitted token must contain.
/virtual_hosts/*/routes/*/jwt_auth/required_type	Required JWT type	string	Required	1 to 64 characters; validated syntax	The required token type value accepted by this route.
/virtual_hosts/*/routes/*/jwt_auth/verification_rate_limit	JWT verification rate limit	object	Required	None at this structural level	A shard-local token bucket that bounds cryptographic verification work.
/virtual_hosts/*/routes/*/jwt_auth/verification_rate_limit/capacity	Verification capacity	integer	Required	1 to 1000000	The maximum verification tokens retained by each shard-local bucket.
/virtual_hosts/*/routes/*/jwt_auth/verification_rate_limit/refill_tokens_per_second	Verification token refill	integer	Required	1 to 1000000	The number of JWT verification tokens replenished per second on each shard.
/virtual_hosts/*/routes/*/local_rate_limit	Local rate limit	object	Optional	None at this structural level	An optional shard-local token bucket applied to this route.
/virtual_hosts/*/routes/*/local_rate_limit/capacity	Rate-limit capacity	integer	Required	1 to 1000000	The maximum request tokens retained by each shard-local route bucket.
/virtual_hosts/*/routes/*/local_rate_limit/refill_tokens_per_second	Rate-limit token refill	integer	Required	1 to 1000000	The number of route-admission tokens replenished per second on each shard.
/virtual_hosts/*/routes/*/match	Route match	object	Required	None at this structural level	The path and optional method, header, and query conditions that select this route.
/virtual_hosts/*/routes/*/match/headers	Header matchers	array<object>	Optional	at most 16 items	The bounded set of downstream request-header predicates required by this route.
/virtual_hosts/*/routes/*/match/headers/*/exact	Exact header value	string	Optional	at most 4096 characters; validated syntax	The exact bounded header value required when this matcher uses value equality.
/virtual_hosts/*/routes/*/match/headers/*/name	Matched header name	string	Required	1 to 128 characters; validated syntax	The HTTP request-header name evaluated by this matcher.
/virtual_hosts/*/routes/*/match/headers/*/present	Header presence	boolean	Optional	None at this structural level	Whether the selected request header must be present or absent.
/virtual_hosts/*/routes/*/match/methods	Matched methods	array<string>	Optional	at most 16 items; items must be unique	The optional explicit HTTP method set accepted by this route.
/virtual_hosts/*/routes/*/match/path_exact	Exact path match	string	Optional	1 to 4096 characters; validated syntax	An absolute request path that must match exactly.
/virtual_hosts/*/routes/*/match/path_prefix	Path-prefix match	string	Optional	1 to 4096 characters; validated syntax	An absolute request-path prefix used to select this route.
/virtual_hosts/*/routes/*/match/query_parameters	Query-parameter matchers	array<object>	Optional	at most 16 items	The bounded set of query-parameter predicates required by this route.
/virtual_hosts/*/routes/*/match/query_parameters/*/exact	Exact query value	string	Optional	at most 4096 characters; validated syntax	The exact bounded query-parameter value required by this matcher.
/virtual_hosts/*/routes/*/match/query_parameters/*/name	Matched query name	string	Required	1 to 256 characters; validated syntax	The query-parameter name evaluated by this matcher.
/virtual_hosts/*/routes/*/match/query_parameters/*/present	Query presence	boolean	Optional	None at this structural level	Whether the selected query parameter must be present or absent.
/virtual_hosts/*/routes/*/match/safe_regex	Safe regular-expression match	string	Optional	1 to 1024 characters	A bounded RE2-compatible request-path expression used to select this route.
/virtual_hosts/*/routes/*/max_concurrent_requests_per_shard	Route concurrency per shard	integer	Optional	1 to 2000000	The maximum requests concurrently admitted to this route on one shard.
/virtual_hosts/*/routes/*/name	Route name	string	Required	at least 1 character	The unique stable route name within its virtual host.
/virtual_hosts/*/routes/*/redirect	Redirect response	object	Optional	None at this structural level	A gateway-generated HTTP redirect action that does not contact an upstream cluster.
/virtual_hosts/*/routes/*/redirect/host	Redirect host	string	Optional	1 to 253 characters; validated syntax	The optional normalized host used to construct the redirect target.
/virtual_hosts/*/routes/*/redirect/path	Redirect path	string	Required	1 to 4096 characters; validated syntax	The absolute non-network-path redirect target path.
/virtual_hosts/*/routes/*/redirect/port	Redirect port	integer	Optional	1 to 65535	The optional TCP port included in the redirect authority.
/virtual_hosts/*/routes/*/redirect/query	Redirect query	string	Optional	at most 4096 characters; validated syntax	The optional query component appended to the redirect target without a leading question mark.
/virtual_hosts/*/routes/*/redirect/scheme	Redirect scheme	string	Optional	one of http, https	The optional HTTP or HTTPS scheme used with an explicit redirect host.
/virtual_hosts/*/routes/*/redirect/status_code	Redirect status	integer	Required	one of 301, 302, 303, 307, 308	The supported 3xx HTTP status returned by this redirect action.
/virtual_hosts/*/routes/*/request_content	Request-content policy	object	Optional	None at this structural level	Optional request media-type and body-size admission rules for this route.
/virtual_hosts/*/routes/*/request_content/allowed_content_types	Allowed content types	array<string>	Optional	1 to 16 items; items must be unique	The explicit media types accepted by this route’s request-content policy.
/virtual_hosts/*/routes/*/request_content/max_body_bytes	Route body limit	integer	Optional	1 to 1073741824	The maximum request-body size in bytes accepted by this route.
/virtual_hosts/*/routes/*/rewrite	Route rewrite	object	Optional	None at this structural level	Optional upstream authority or path rewriting applied after route selection.
/virtual_hosts/*/routes/*/rewrite/host	Rewritten host	string	Optional	1 to 253 characters; validated syntax	The normalized upstream host used after this rewrite.
/virtual_hosts/*/routes/*/rewrite/path	Rewritten exact path	string	Optional	1 to 4096 characters; validated syntax	The absolute path that replaces the complete matched request path.
/virtual_hosts/*/routes/*/rewrite/path_prefix	Rewritten path prefix	string	Optional	1 to 4096 characters; validated syntax	The absolute prefix that replaces the matched route prefix while preserving the suffix.
/virtual_hosts/*/routes/*/rewrite/port	Rewritten port	integer	Optional	1 to 65535	The optional upstream authority port used with a rewritten host.
/virtual_hosts/*/routes/*/source_ip_policy	Source-IP policy	object	Optional	None at this structural level	Optional allow or deny CIDR admission based on the resolved downstream client address.
/virtual_hosts/*/routes/*/source_ip_policy/allow_cidrs	Allowed source networks	array<string>	Optional	1 to 64 items; items must be unique	The CIDR set from which resolved client addresses are admitted.
/virtual_hosts/*/routes/*/source_ip_policy/deny_cidrs	Denied source networks	array<string>	Optional	1 to 64 items; items must be unique	The CIDR set from which resolved client addresses are rejected.
/virtual_hosts/*/routes/*/websocket	WebSocket policy	object	Optional	None at this structural level	Enables bounded WebSocket upgrade and forwarding behavior for an upstream route.
/virtual_hosts/*/routes/*/websocket/idle_timeout_ms	WebSocket idle timeout	integer	Optional	1000 to 3600000	The maximum idle period in milliseconds for an upgraded WebSocket connection.
/virtual_hosts/*/routes/*/weighted_clusters	Weighted clusters	array<object>	Optional	2 to 16 items	The bounded set of named clusters and relative weights used for deterministic traffic distribution.
/virtual_hosts/*/routes/*/weighted_clusters/*/cluster	Weighted cluster name	string	Required	at least 1 character	The named upstream cluster represented by this weighted entry.
/virtual_hosts/*/routes/*/weighted_clusters/*/weight	Cluster weight	integer	Required	1 to 4096	The positive relative traffic weight assigned to this cluster.

Clusters, health, retries, and endpoints

Clusters describe upstream pools, connection limits, transport security, health behavior, retry budgets, and concrete endpoints.

YAML path	Parameter	Type	Direct presence	Constraints	Meaning
/clusters	Clusters	array<object>	Required	at least 1 item	The non-empty set of named upstream service pools available to routes.
/clusters/*/active_health	Active health checks	object	Optional	None at this structural level	Optional periodic HTTP health probing for endpoints in this cluster.
/clusters/*/active_health/expected_status_max	Maximum healthy status	integer	Optional	200 to 599	The inclusive highest HTTP response status considered healthy by an active probe.
/clusters/*/active_health/expected_status_min	Minimum healthy status	integer	Optional	200 to 599	The inclusive lowest HTTP response status considered healthy by an active probe.
/clusters/*/active_health/healthy_threshold	Healthy threshold	integer	Optional	1 to 100	The consecutive successful probes required before an endpoint becomes healthy.
/clusters/*/active_health/host	Health-check host	string	Optional	1 to 253 characters	The HTTP Host or authority value used by active health-check requests.
/clusters/*/active_health/interval_ms	Health-check interval	integer	Optional	1000 to 300000	The delay in milliseconds between scheduled active health probes.
/clusters/*/active_health/path	Health-check path	string	Optional	1 to 4096 characters; validated syntax	The absolute HTTP request path used for active health probes.
/clusters/*/active_health/timeout_ms	Health-check timeout	integer	Optional	100 to 10000	The maximum time in milliseconds allowed for one active health probe.
/clusters/*/active_health/unhealthy_threshold	Unhealthy threshold	integer	Optional	1 to 100	The consecutive failed probes required before an endpoint becomes unhealthy.
/clusters/*/connect_timeout_ms	Connect timeout	integer	Optional	1 to 60000	The maximum time in milliseconds allowed to establish an upstream connection.
/clusters/*/dns_refresh	DNS refresh	object	Optional	None at this structural level	Optional bounded asynchronous hostname-resolution policy for cluster endpoints.
/clusters/*/dns_refresh/refresh_interval_ms	DNS refresh interval	integer	Optional	1000 to 3600000	The interval in milliseconds between accepted endpoint hostname refreshes.
/clusters/*/dns_refresh/resolve_timeout_ms	DNS resolution timeout	integer	Optional	100 to 10000	The maximum time in milliseconds allowed for one endpoint hostname resolution.
/clusters/*/endpoints	Endpoints	array<object>	Required	1 to 4096 items	The non-empty set of upstream network destinations owned by this cluster.
/clusters/*/endpoints/*/address	Endpoint address	string	Required	at least 1 character	The IP address or hostname used to connect to this upstream endpoint.
/clusters/*/endpoints/*/name	Endpoint name	string	Required	at least 1 character	The unique stable name of this endpoint within its cluster.
/clusters/*/endpoints/*/port	Endpoint port	integer	Required	1 to 65535	The TCP port used to connect to this upstream endpoint.
/clusters/*/endpoints/*/weight	Endpoint weight	integer	Optional	1 to 4096	The relative endpoint selection weight used by a compatible load-balancing policy.
/clusters/*/load_balancing_policy	Load-balancing policy	string	Required	one of round_robin, least_request, random	The reviewed algorithm used to select an eligible endpoint for each request.
/clusters/*/max_concurrent_requests_per_endpoint	Endpoint request limit	integer	Optional	1 to 2000000	The maximum concurrent requests admitted to one endpoint before bounded rejection or alternate selection.
/clusters/*/max_connections_per_shard	Connections per shard	integer	Optional	1 to 1000000	The maximum shard-local upstream connections retained for this cluster.
/clusters/*/max_http2_streams_per_connection	HTTP/2 streams per connection	integer	Optional	1 to 1000	The maximum concurrent HTTP/2 streams admitted on one upstream connection.
/clusters/*/max_pending_requests_per_shard	Pending requests per shard	integer	Optional	1 to 1000000	The maximum shard-local requests allowed to wait for upstream capacity.
/clusters/*/name	Cluster name	string	Required	at least 1 character	The unique stable cluster name referenced by routes and weighted-cluster entries.
/clusters/*/passive_health	Passive health	object	Optional	None at this structural level	Optional endpoint ejection and recovery policy driven by proxied request outcomes.
/clusters/*/passive_health/consecutive_failures	Failure threshold	integer	Optional	1 to 100	The consecutive qualifying failures required before passive endpoint ejection.
/clusters/*/passive_health/consecutive_successes	Recovery threshold	integer	Optional	1 to 100	The consecutive successful observations required before passive recovery.
/clusters/*/passive_health/ejection_time_ms	Ejection duration	integer	Optional	100 to 300000	The bounded time in milliseconds an unhealthy endpoint remains passively ejected.
/clusters/*/passive_health/max_ejection_percent	Maximum ejection percentage	integer	Optional	1 to 100	The maximum percentage of cluster endpoints that passive health may eject at once.
/clusters/*/protocol	Upstream protocol	string	Optional	one of http1, http2	The application protocol BonVoyage uses when forwarding requests to this cluster.
/clusters/*/retry	Retry policy	object	Optional	None at this structural level	Optional bounded retry behavior for eligible failures and request methods.
/clusters/*/retry/budget	Retry budget	object	Optional	None at this structural level	Shard-local token and concurrency limits that contain retry amplification.
/clusters/*/retry/budget/capacity	Retry budget capacity	integer	Optional	1 to 1000000	The maximum number of retry tokens retained by the shard-local budget.
/clusters/*/retry/budget/max_concurrent_retries_per_shard	Concurrent retries per shard	integer	Optional	1 to 1000000	The maximum retries executing concurrently on one data-plane shard.
/clusters/*/retry/budget/refill_tokens_per_second	Retry token refill	integer	Optional	1 to 1000000	The number of retry-budget tokens replenished per second on each shard.
/clusters/*/retry/max_attempts	Maximum attempts	integer	Optional	2 to 5	The total bounded upstream attempts permitted for one eligible request.
/clusters/*/retry/per_try_timeout_ms	Per-try timeout	integer	Optional	10 to 60000	The maximum time in milliseconds allowed for each individual upstream attempt.
/clusters/*/retry/retryable_methods	Retryable methods	array<string>	Optional	1 to 5 items; items must be unique	The explicit HTTP methods eligible for this cluster retry policy.
/clusters/*/upstream_tls	Upstream TLS	object	Optional	None at this structural level	TLS server verification and optional client-certificate settings for this cluster.
/clusters/*/upstream_tls/certificate_chain_secret	Client certificate secret	string	Optional	validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing the client certificate chain used for upstream mTLS.
/clusters/*/upstream_tls/private_key_secret	Client private-key secret	string	Optional	validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing the private key used for upstream mTLS.
/clusters/*/upstream_tls/server_name	TLS server name	string	Required	1 to 253 characters; validated syntax	The expected upstream server identity used for SNI and certificate verification.
/clusters/*/upstream_tls/trust_bundle_secret	Upstream trust-bundle secret	string	Required	validated syntax; deployment-secret filename only; never secret contents	The deployment-secret filename containing trusted certificate authorities for the upstream server.

Runtime limits

Runtime limits bound request sizes, timeouts, response metadata, idle connections, and downstream connection density.

YAML path	Parameter	Type	Direct presence	Constraints	Meaning
/runtime_limits	Runtime limits	object	Optional	None at this structural level	Optional global safety ceilings applied by the data plane for this snapshot.
/runtime_limits/downstream_idle_timeout_ms	Downstream idle timeout	integer	Optional	1 to 3600000	The maximum downstream connection idle period in milliseconds.
/runtime_limits/max_downstream_connections_per_shard	Downstream connections per shard	integer	Optional	1 to 1000000	The maximum downstream connections admitted by one data-plane shard.
/runtime_limits/max_request_body_bytes	Maximum request body	integer	Optional	1 to 1073741824	The global maximum accepted downstream request-body size in bytes.
/runtime_limits/max_request_header_bytes	Maximum request headers	integer	Optional	1024 to 1048576	The global maximum accepted downstream request-header size in bytes.
/runtime_limits/max_upstream_chunk_metadata_bytes	Maximum chunk metadata	integer	Optional	1024 to 1048576	The maximum upstream chunk-metadata bytes retained while processing a response.
/runtime_limits/max_upstream_response_header_bytes	Maximum response headers	integer	Optional	1024 to 1048576	The maximum accepted upstream response-header size in bytes.
/runtime_limits/request_timeout_ms	Request timeout	integer	Optional	1 to 300000	The global maximum request lifetime in milliseconds unless a stricter boundary applies.

Authority and defaults

This page describes source syntax. Optional fields may receive safe compiler defaults, but the formatter deliberately does not materialize those defaults into YAML. Do not infer a default merely because a field is optional. Validate with the exact installed release and inspect preview output before rollout.

The catalog does not prove that a gateway received, ACKed, or activated a snapshot. Runtime confirmation remains a separate management and traffic test.