The configuration model

Arion is configured by one YAML file whose top-level keys tune the process and whose envoy_bootstrap key carries the actual proxy resources in Envoy's own format — this page explains that split and everything that can override it. Read it before writing your first proxy config; examples marked as proxy configuration fragments fit inside this file.

Why it matters

The model draws a deliberate line. Process-level concerns — threading, logging, metrics — are Arion's own keys, small and stable. Everything that describes traffic — listeners, clusters, routes, secrets — lives inside envoy_bootstrap in standard Envoy syntax, which is why existing Envoy configs, control planes, and tooling carry over (see the compatibility promise). Knowing which side of the line a setting sits on tells you where to look it up and whether an environment variable can change it.

How it works

The file has six top-level keys. runtime, logging, access_logging, metrics, and timezone configure the process; the resources come from at most one of bootstrap (Arion's native format) or envoy_bootstrap (an Envoy v3 bootstrap, verbatim). Setting both is an error, and a config that ends up with no listeners and no ADS cluster is refused at startup because there is nothing to serve. Every key has a default; the documentation uses envoy_bootstrap throughout.

runtime:
  num_cpus: 4
  num_runtimes: 2
logging:
  log_level: info
envoy_bootstrap:
  dynamic_resources:
    ads_config:
      grpc_services:
        - envoy_grpc: { cluster_name: xds }
  static_resources:
    clusters:
      # the xds cluster, plus any static listeners and clusters

Flags and environment variables

The command line selects the file and can override the runtime block; it never changes resources. arion -c arion.yaml is the normal invocation. --with-envoy-bootstrap envoy.yaml loads a plain, unmodified Envoy bootstrap file — either on its own (no -c, defaults for everything else) or alongside -c, in which case it replaces the file's bootstrap. The runtime flags mirror the runtime keys: --num-cpus, --num-runtimes, --num-service-threads, --global-queue-interval, --event-interval, --max-io-events-per-tick.

Environment variables cover the same runtime settings for container use — ARION_CPU_LIMIT (alias ARION_GATEWAY_CORES), ARION_GATEWAY_RUNTIMES, ARION_SERVICE_THREADS, and ARION_RT_* for the Tokio tuning knobs. Precedence is environment variable, then flag, then file. The full lists live in the CLI and environment variable references.

Static and dynamic resources

static_resources — listeners, clusters, and secrets — are parsed, validated, and live before the first connection is accepted. dynamic_resources instead delegates to a control plane: ads_config names a cluster (defined in static_resources) that serves aggregated xDS over gRPC, and Arion subscribes to listener, cluster, route, endpoint, and secret updates on that stream. The two mix freely — a common pattern is static listeners whose route configuration arrives via rds with config_source: { ads: {} }. Resources are identical in both channels; a listener delivered over xDS is parsed by the same code, and rejected under the same rules, as one written in the file. See xDS control planes for the operational side.

The Arion control plane also accepts YAML resource documents through arionctl apply. These use apiVersion: ctl.arion.io/v1alpha1, with resource identity and fleet in metadata and the Envoy resource in spec. They configure the resources delivered over xDS; proxy process settings and the connection to the control plane remain in the bootstrap file described here.

Arion validates the entire file before starting any runtime. A misspelled key, an unsupported Envoy field, or both bootstrap and envoy_bootstrap set will stop the process with an error naming the offending path — nothing is silently ignored.

Key terms

• envoy_bootstrap — the top-level key holding a standard Envoy v3 bootstrap; the canonical dialect in these docs.
• Native bootstrap — the same model in Arion's own YAML shape, under bootstrap.
• Static resources — listeners, clusters, and secrets defined in the file and live at startup.
• Dynamic resources — resources subscribed from a control plane over the ADS stream.
• Runtime overrides — environment variables and flags that adjust the runtime block only.

Next

• Every top-level key and field: the file format reference.
• What the runtime block actually controls: runtime and threading.
• Serve the bootstrap's resources from a control plane: xDS control planes.