Envoy compatibility is Arion's contract with your existing configuration: if Arion accepts a config that was written for Envoy, it behaves essentially like Envoy — and if it cannot honor part of that config, it refuses to parse the file, or rejects the xDS update. This page defines both halves of that sentence, so you know exactly what a successful startup does and does not guarantee.
Why it matters
Arion supports a subset of Envoy, not all of it. Without a hard rule, a subset is dangerous: a proxy that silently ignored an RBAC filter it did not understand would still start, still serve traffic, and quietly drop your security policy. Arion takes the opposite stance — every part of a config is either implemented or rejected — which makes the safe conclusion valid: if it starts, it is enforcing what you wrote. That is what lets you point an existing control plane at Arion, or migrate a working envoy.yaml, and trust the result.
What "essentially like Envoy" covers
Accepted configuration follows Envoy's behavior at the level that decides correctness:
- Filter execution. Filters run in the expected order and at the expected attachment points, with the same request/response semantics — see the filter chain.
- Routing decisions. Virtual host and route matching, per-route overrides, redirects, direct responses, and the choice of cluster resolve the way Envoy resolves them.
- Acceptance and rejection. A request that Envoy would reject — by RBAC, a rate limit, a JWT rule — is rejected by Arion, and vice versa.
What may differ are the less crucial behaviors: the exact set and shape of emitted statistics, and implementation details inside load-balancing algorithms (a ROUND_ROBIN cluster balances round-robin, but the internal state machine is Arion's own). Where Arion deliberately diverges, the divergence is documented on the relevant page. The intent in one sentence: it should be safe to replace Envoy with Arion.
How rejection works
When Arion converts an Envoy resource, it examines every field of every message. Each field is either mapped onto Arion's own configuration model or classified as unsupported — there is no third category, and unknown or unsupported input is never skipped. The same applies to enum variants and to constraints Envoy enforces beyond the schema, such as the router being the final HTTP filter. This is checked at the parser level, so an unsupportable config is unrepresentable in the running process.
The consequence depends on where the config came from:
- From a file (
envoy_bootstrapor--with-envoy-bootstrap): Arion exits at startup with an error that names the full path to the offending field. - From xDS: a decoding or conversion failure rejects the whole response before any of its updates or removals are applied. Arion sends a NACK to the control plane with the error detail. Later failures while applying decoded resources also produce a NACK, but do not roll back successful changes in that response.
A refused config is the feature working as designed, not an interoperability bug. Consult the supported configuration matrix for what Arion accepts today; fields marked unsupported must be removed from the config rather than left in place.
Because acceptance is field-by-field, compatibility grows without ever changing the meaning of an accepted config: when a field becomes supported, configs that previously failed start working — configs that already worked keep behaving the same.
Key terms
- Compatibility promise — accepted Envoy config behaves essentially like Envoy; unsupported config is refused.
- Unsupported field — an Envoy field Arion does not implement; using it fails parsing instead of being ignored.
- NACK — an xDS acknowledgement reporting a rejected update and its reason; application failures can leave some changes applied.
- Supported subset — the portion of the Envoy API Arion implements, cataloged in the reference matrix.
Next
- Check a config against the supported configuration matrix.
- Run Arion behind your existing control plane: xDS control planes.
- Move a working Envoy deployment over with the migration guide.