Routes

A route configuration is written inline under the HTTP connection manager's route_config (or fetched over ADS with rds); the fields below are the Envoy field names Arion accepts, and any other field makes it refuse the configuration.

route_config

Field	Type	Required	Default	Description
`name`	string	yes	—	Route configuration name.
`virtual_hosts`	list	yes	—	At least one virtual host.
`request_headers_to_add`	list	no	`[]`	Header mutations applied to every request.
`request_headers_to_remove`	list	no	`[]`	Header names removed from every request.
`response_headers_to_add`	list	no	`[]`	Header mutations applied to every response.
`response_headers_to_remove`	list	no	`[]`	Header names removed from every response.
`most_specific_header_mutations_wins`	bool	no	`false`	Apply route-level mutations after virtual-host and global ones instead of before.

Virtual hosts

Field	Type	Required	Default	Description
`name`	string	yes	—	Virtual host name.
`domains`	list	yes	—	Host names to match: exact (`api.example.com`), suffix (`.example.com`), prefix (`example.`) or ``. One wildcard, only at the start or end. Exact beats suffix, suffix beats prefix, `` matches last; longer matches win within a kind.
`routes`	list	no	`[]`	Routes, evaluated in order; the first match wins.
`retry_policy`	object	no	—	Default retry policy for routes in this host.
`request_headers_to_add` / `request_headers_to_remove`	list	no	`[]`	Request header mutations for this host.
`response_headers_to_add` / `response_headers_to_remove`	list	no	`[]`	Response header mutations for this host.

Routes

Each route has a match and exactly one action: route, redirect or direct_response.

Field	Type	Required	Default	Description
`name`	string	no	`""`	Route name; rendered by the `%ROUTE_NAME%` access-log operator.
`match`	object	yes	—	Match criteria.
`route`	object	one of	—	Forward to a cluster (route action).
`redirect`	object	one of	—	Return an HTTP redirect.
`direct_response`	object	one of	—	Return a fixed response.
`typed_per_filter_config`	map	no	`{}`	Per-route filter overrides, keyed by filter name.
`request_headers_to_add` / `request_headers_to_remove`	list	no	`[]`	Request header mutations for this route.
`response_headers_to_add` / `response_headers_to_remove`	list	no	`[]`	Response header mutations for this route.

Route match

Field	Type	Required	Default	Description
`prefix`	string	one of	—	Path prefix match.
`path`	string	one of	—	Exact path match.
`safe_regex`	object	one of	—	`{regex: "..."}`; must match the full path.
`path_separated_prefix`	string	one of	—	Matches `/api`, `/api/` and `/api/...` but not `/apiv2`. Must not end in `/` or contain `?`.
`case_sensitive`	bool	no	`true`	Case sensitivity for `prefix`, `path` and `path_separated_prefix` (not regex).
`headers`	list	no	`[]`	Header matchers; all must match.
`query_parameters`	list	no	`[]`	Query parameter matchers; all must match.

If no path specifier is given, the route matches every path.

routes:
  - match:
      prefix: "/api"
      headers:
        - name: ":method"
          string_match: { exact: "GET" }
      query_parameters:
        - name: version
          string_match: { exact: "v1" }
    route:
      cluster: api

Header matchers

name may be a regular header or one of the pseudo-headers :method, :path, :scheme.

Field	Type	Required	Default	Description
`name`	string	yes	—	Header (or pseudo-header) to inspect.
`string_match`	object	one of	—	One of `exact`, `prefix`, `suffix`, `contains` or `safe_regex`, plus optional `ignore_case` (bool).
`exact_match` / `prefix_match` / `suffix_match` / `contains_match`	string	one of	—	Shorthand forms (case sensitive).
`safe_regex_match`	object	one of	—	`{regex: "..."}`.
`present_match`	bool	one of	—	Match when the header exists (any value). Combine with `invert_match` for "absent".
`invert_match`	bool	no	`false`	Invert the result. A missing header only inverts for `present_match`.
`treat_missing_header_as_empty`	bool	no	`false`	Evaluate a missing header as `""`. Ignored for `present_match`.

range_match is not supported.

Query parameter matchers

Field	Type	Required	Default	Description
`name`	string	yes	—	Query parameter name (case sensitive; first occurrence wins).
`string_match`	object	no	—	Same shape as the header `string_match`.
`present_match`	bool	no	`true`	Match on presence or absence. Used when `string_match` is not set.

Route action

Field	Type	Required	Default	Description
`cluster`	string	one of	—	Name of the target cluster.
`weighted_clusters`	object	one of	—	Weighted split (below).
`cluster_header`	string	one of	—	Take the cluster name from this request header.
`timeout`	duration	no	`15s`	Whole-request upstream timeout, including retries. `0s` disables it.
`cluster_not_found_response_code`	enum	no	`SERVICE_UNAVAILABLE`	Also `NOT_FOUND` or `INTERNAL_SERVER_ERROR`.
`prefix_rewrite`	string	no	—	Replace the matched prefix before forwarding. Mutually exclusive with `regex_rewrite`.
`regex_rewrite`	object	no	—	`{pattern: {regex: "..."}, substitution: "..."}` applied to the path.
`retry_policy`	object	no	—	Route-level retry policy; overrides the virtual host's.
`priority`	enum	no	`DEFAULT`	Routing priority (`DEFAULT` or `HIGH`); selects the matching circuit-breaker thresholds.
`hash_policy`	list	no	`[]`	Hash policies for `RING_HASH` / `MAGLEV` clusters.
`upgrade_configs`	list	no	`[]`	`{upgrade_type, enabled}` entries. Only `websocket` can be enabled; `connect` is accepted only with `enabled: false`.

weighted_clusters

Traffic is split in proportion to the weights.

Field	Type	Required	Default	Description
`clusters`	list	yes	—	One entry per target.
`clusters[].name`	string	yes	—	Cluster name.
`clusters[].weight`	uint32	yes	—	Relative weight, at least 1.

route:
  weighted_clusters:
    clusters:
      - name: backend-v1
        weight: 90
      - name: backend-v2
        weight: 10

hash_policy

Policies are applied in order and their hashes combined; a matching terminal policy stops the list, and if nothing matches a random hash is used.

Field	Type	Required	Default	Description
`header`	object	one of	—	`{header_name: "..."}` — hash that header's value.
`query_parameter`	object	one of	—	`{name: "..."}` — hash that query parameter's value.
`connection_properties`	object	one of	—	`{source_ip: true}` — hash the source address.
`terminal`	bool	no	`false`	Stop evaluating further policies when this one applies.

Retry policy

Available on virtual hosts and route actions.

Field	Type	Required	Default	Description
`retry_on`	string	yes	—	Comma-separated conditions: `5xx`, `gateway-error`, `reset`, `connect-failure`, `envoy-ratelimited`, `retriable-4xx`, `refused-stream`, `retriable-status-codes`, `retriable-headers`, `http3-post-connect-failure`.
`num_retries`	uint32	no	`1`	Maximum retry attempts.
`per_try_timeout`	duration	no	none	Timeout per attempt. Unset means attempts are bounded only by the route `timeout`.
`retriable_status_codes`	list	no	`[]`	Status codes for `retriable-status-codes`.
`retry_back_off`	object	no	`25ms`/`250ms`	`{base_interval, max_interval}` for exponential backoff. `base_interval` is rounded up to at least 1ms; `max_interval` defaults to 10x the base and must not be smaller than it.
`retriable_headers`	list	no	`[]`	Header matchers against the response, for `retriable-headers`.
`retriable_request_headers`	list	no	`[]`	Request headers that must be present for retries to be attempted.

route:
  cluster: api
  timeout: 10s
  retry_policy:
    retry_on: "5xx,reset"
    num_retries: 3
    per_try_timeout: 2s
    retry_back_off:
      base_interval: 0.05s
      max_interval: 0.5s

Redirect

Field	Type	Required	Default	Description
`response_code`	enum	no	`MOVED_PERMANENTLY`	Also `FOUND`, `SEE_OTHER`, `TEMPORARY_REDIRECT`, `PERMANENT_REDIRECT`.
`host_redirect`	string	no	—	Replace the host.
`port_redirect`	uint16	no	—	Replace the port. Combined with `host_redirect` they must form a valid authority.
`scheme_redirect`	string	one of	—	Replace the scheme (for example `https`).
`https_redirect`	bool	one of	—	Shorthand for redirecting to `https`.
`path_redirect`	string	one of	—	Replace the whole path.
`prefix_rewrite`	string	one of	—	Replace the matched prefix in the redirect target.
`regex_rewrite`	object	one of	—	`{pattern: {regex}, substitution}` applied to the path.
`strip_query`	bool	no	`false`	Drop the query string from the redirect target.

Direct response

Field	Type	Required	Default	Description
`status`	uint32	yes	—	HTTP status code to return.
`body`	object	no	empty	A data source (`inline_string`, `inline_bytes`, `filename` or `environment_variable`), read once at configuration load.

routes:
  - match:
      prefix: "/healthz"
    direct_response:
      status: 200
      body:
        inline_string: "ok"

Header mutations

*_headers_to_add entries wrap a header and an append behavior; *_headers_to_remove entries are plain header names.

Field	Type	Required	Default	Description
`header.key`	string	yes	—	Header name.
`header.value`	string	one of	—	Header value. Supports access-log command operators such as `%REQ(:PATH)%` or `%DOWNSTREAM_REMOTE_ADDRESS%`.
`header.raw_value`	bytes	one of	—	Raw value alternative to `value`; setting both is an error.
`append_action`	enum	no	`APPEND_IF_EXISTS_OR_ADD`	Also `ADD_IF_ABSENT`, `OVERWRITE_IF_EXISTS_OR_ADD`, `OVERWRITE_IF_EXISTS`.
`keep_empty_value`	bool	no	`false`	Keep the header when its rendered value is empty.

request_headers_to_add:
  - header:
      key: x-original-path
      value: "%REQ(:PATH)%"
    append_action: OVERWRITE_IF_EXISTS_OR_ADD
request_headers_to_remove:
  - x-internal-debug

typed_per_filter_config

A map from the name of a filter in http_filters to an override; the named filter must exist and the override type must match its type.

`@type` (under `type.googleapis.com/`)	Overrides	Description
`envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit`	local rate limit	Replaces the filter's settings on this route.
`envoy.extensions.filters.http.rbac.v3.RBACPerRoute`	HTTP RBAC	`{rbac: ...}`; an empty override disables RBAC for the route.
`envoy.extensions.filters.http.ext_proc.v3.ExtProcPerRoute`	external processing	Disables or overrides ext_proc on this route.
`envoy.config.route.v3.FilterConfig`	any of the above	Wrapper with `disabled: true` to switch a filter off for the route, or `config` carrying one of the overrides. `is_optional` is not supported.

Reference and guides