envoyproxy/envoy

Configuration reference

This page summarises Envoy's configuration entry points. The authoritative reference for each field is on envoyproxy.io; here we sketch the shape and point at the proto sources.

Bootstrap

The root config is envoy.config.bootstrap.v3.Bootstrap (api/envoy/config/bootstrap/v3/bootstrap.proto). Every Envoy process starts with a bootstrap loaded from --config-path (YAML / JSON / proto-text) or --config-yaml. Top-level fields:

Field	Type	Purpose
`node`	`Node`	Identity (cluster, id, locality) presented to xDS and observability.
`static_resources`	`StaticResources`	Listeners, clusters, secrets baked into the file.
`dynamic_resources`	`DynamicResources`	LDS / CDS / ADS configuration sources.
`cluster_manager`	`ClusterManager`	Outlier event log, upstream binding, secondary thread pool.
`hds_config`	`ApiConfigSource`	Health discovery service.
`flags_path`	`string`	Directory of feature flag override files.
`stats_sinks`	`repeated StatsSink`	Where stats go.
`stats_config`	`StatsConfig`	Tag rules, matchers, histogram buckets.
`stats_flush_interval`	`Duration`	Flush cadence (default 5s).
`watchdog` / `watchdogs`	`Watchdog`	Per-thread watchdog.
`tracing`	`Tracing`	Default tracer.
`layered_runtime`	`LayeredRuntime`	Runtime layer config (static, admin, RTDS).
`admin`	`Admin`	The admin endpoint.
`overload_manager`	`OverloadManager`	Resource-pressure actions.
`application_log_config`	`ApplicationLogConfig`	Log format and sinks.
`default_socket_interface`	`string`	Override default socket interface (e.g. for VPP/VCL).
`bootstrap_extensions`	`repeated TypedExtensionConfig`	Long-lived bootstrap-time plug-ins.
`fatal_actions`	`repeated FatalAction`	Hooks on assert / segfault.
`xds_delegate_extension`	`TypedExtensionConfig`	Custom xDS persistence.

Listener

Listener config is at api/envoy/config/listener/v3/listener.proto. Key parts:

name — operator-visible identifier.
address — single bind address (or additional_addresses for multi-bind).
filter_chains — list with optional filter_chain_match predicates.
default_filter_chain — fallback when no chain matches.
listener_filters — pre-chain inspection (TLS / proxy-protocol / SNI / HTTP-inspector).
listener_filters_timeout — timeout for inspection.
udp_listener_config — UDP-only.
connection_balance_config — exact-balance vs free.
socket_options — raw setsockopt.
traffic_direction — INBOUND / OUTBOUND, mainly for logging.
enable_reuse_port, transparent, freebind, tcp_fast_open_queue_length — kernel-level options.

Cluster

Cluster config is at api/envoy/config/cluster/v3/cluster.proto. Key parts:

name — operator-visible identifier.
type — STATIC, STRICT_DNS, LOGICAL_DNS, EDS, ORIGINAL_DST.
connect_timeout, per_connection_buffer_limit_bytes.
lb_policy (legacy) or load_balancing_policy (new).
load_assignment — static endpoints or template.
eds_cluster_config — for EDS-typed clusters.
health_checks — active health checking.
outlier_detection — passive ejection.
circuit_breakers — per-priority resource budgets.
transport_socket / transport_socket_matches — TLS, ALTS, raw.
typed_extension_protocol_options — protocol-specific options keyed by extension name (HTTP, HTTP/2, HTTP/3, TCP).
wait_for_warm_on_init — gate readiness on initial endpoint reception.

HTTP connection manager

api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto. Key parts:

codec_type — AUTO / HTTP1 / HTTP2 / HTTP3.
stat_prefix — root for all stats from this HCM.
route_config (inline) or rds (dynamic) or scoped_routes.
http_filters — the L7 filter chain.
tracing — sampling and decoration.
access_log, access_log_options — per-stream log emission.
*_protocol_options — per-codec knobs (frame size, GOAWAY, max headers).
request_timeout, request_headers_timeout, stream_idle_timeout, idle_timeout.
xff_num_trusted_hops, internal_address_config, original_ip_detection_extensions.
local_reply_config — custom 4xx/5xx body template.
path_normalization_options — RFC 3986 normalisation, merge slashes.

Route configuration

envoy.config.route.v3.RouteConfiguration (api/envoy/config/route/v3/route.proto):

name, virtual_hosts (or vhds).
internal_only_headers, response_headers_to_add, request_headers_to_add — header manipulation.
validate_clusters — gate config acceptance on cluster existence.
most_specific_header_mutations_wins, cluster_specifier_plugins, metadata.

VirtualHost: domains, routes, typed_per_filter_config, cors, rate_limits, request_mirror_policies, retry_policy.

Route: match (path, headers, query, runtime), route (cluster routing) / redirect / direct_response / filter_action, metadata, decorator, tracing, typed_per_filter_config.

RouteAction: cluster / cluster_header / weighted_clusters, prefix_rewrite, regex_rewrite, host_rewrite, timeout, idle_timeout, retry_policy, request_mirror_policies, hash_policy, auto_host_rewrite, rate_limits, internal_redirect_policy, early_data_policy, cluster_specifier_plugin.

Command-line flags

source/server/options_impl_base.cc and the CLI helpers in source/exe/ define the flags:

Flag	Purpose
`-c`, `--config-path`	Bootstrap file path.
`--config-yaml`	Inline YAML bootstrap (merged with `--config-path`).
`--service-cluster`	Override `node.cluster`.
`--service-node`	Override `node.id`.
`--service-zone`	Override `node.locality.zone`.
`--concurrency`	Worker count (default = number of CPUs).
`--restart-epoch`	Hot-restart generation.
`--base-id`	Hot-restart base identifier.
`--use-dynamic-base-id`	Auto-allocate.
`--drain-time-s`, `--parent-shutdown-time-s`	Drain durations.
`--log-level`	Default log level (`trace`/`debug`/`info`/`warn`/`error`/`critical`/`off`).
`--component-log-level`	Per-component override (e.g. `--component-log-level upstream:debug,connection:trace`).
`--log-format`, `--log-format-escaped`, `--log-path`	Log formatting / sink.
`--mode`	`serve` / `validate`.
`--reject-unknown-dynamic-fields`, `--ignore-unknown-dynamic-fields`	Strict-vs-lenient xDS validation.
`--admin-address-path`	Where admin writes its bound address.
`--allow-unknown-static-fields`	Strict-vs-lenient bootstrap validation.
`--bootstrap-version`	Force bootstrap proto major version.
`--enable-fine-grain-logging`	Per-file log levels.
`--cpuset-threads`	Use cpuset count for worker count.
`--disable-extensions`	Comma-separated extension names to disable.
`--enable-mutex-tracing`	Mutex contention tracing.
`--socket-mode`, `--socket-path`	Domain socket admin / hot-restart.

Validation

The --mode validate flag loads the config, builds listeners and clusters, and exits. CI uses this to check sample configs.

envoy -c my_config.yaml --mode validate

Defaults and merging

--config-path and --config-yaml merge: the YAML inline overlays the file.
Static and dynamic resources merge: static_resources.clusters and dynamic_resources.cds_config's clusters can coexist.
Filter chains merge — but routes, listeners, and clusters with the same name in static and dynamic config conflict; the static ones load first and dynamic fail.