Overview (v1 API)

Attention

The v1 configuration/API is now considered legacy and the deprecation schedule has been announced. Please upgrade and use the v2 configuration/API.

The Envoy configuration format is written in JSON and is validated against a JSON schema. The schema can be found in source/common/json/config_schemas.cc. The main configuration for the server is contained within the listeners and cluster manager sections. The other top level elements specify miscellaneous configuration.

YAML support is also provided as a syntactic convenience for hand-written configurations. Envoy will internally convert YAML to JSON if a file path ends with .yaml. In the rest of the configuration documentation, we refer exclusively to JSON. Envoy expects unambiguous YAML scalars, so if a cluster name (which should be a string) is called true, it should be written in the configuration YAML as “true”. The same applies to integer and floating point values (e.g. 1 vs. 1.0 vs. “1.0”).

  1. {
  2.   "listeners": [],
  3.   "lds": "{...}",
  4.   "admin": "{...}",
  5.   "cluster_manager": "{...}",
  6.   "flags_path": "...",
  7.   "statsd_udp_ip_address": "...",
  8.   "statsd_tcp_cluster_name": "...",
  9.   "stats_flush_interval_ms": "...",
  10.   "watchdog_miss_timeout_ms": "...",
  11.   "watchdog_megamiss_timeout_ms": "...",
  12.   "watchdog_kill_timeout_ms": "...",
  13.   "watchdog_multikill_timeout_ms": "...",
  14.   "tracing": "{...}",
  15.   "rate_limit_service": "{...}",
  16.   "runtime": "{...}",
  17. }

listeners

(required, array) An array of listeners that will be instantiated by the server. A single Envoy process can contain any number of listeners.

lds

(optional, object) Configuration for the Listener Discovery Service (LDS). If not specified only static listeners are loaded.

admin

(required, object) Configuration for the local administration HTTP server.

cluster_manager

(required, object) Configuration for the cluster manager which owns all upstream clusters within the server.

flags_path

(optional, string) The file system path to search for startup flag files.

statsd_udp_ip_address

(optional, string) The UDP address of a running statsd compliant listener. If specified, statistics will be flushed to this address. IPv4 addresses should have format host:port (ex: 127.0.0.1:855). IPv6 addresses should have URL format [host]:port (ex: [::1]:855).

statsd_tcp_cluster_name

(optional, string) The name of a cluster manager cluster that is running a TCP statsd compliant listener. If specified, Envoy will connect to this cluster to flush statistics.

stats_flush_interval_ms

(optional, integer) The time in milliseconds between flushes to configured stats sinks. For performance reasons Envoy latches counters and only flushes counters and gauges at a periodic interval. If not specified the default is 5000ms (5 seconds).

watchdog_miss_timeout_ms

(optional, integer) The time in milliseconds after which Envoy counts a nonresponsive thread in the “server.watchdog_miss” statistic. If not specified the default is 200ms.

watchdog_megamiss_timeout_ms

(optional, integer) The time in milliseconds after which Envoy counts a nonresponsive thread in the “server.watchdog_mega_miss” statistic. If not specified the default is 1000ms.

watchdog_kill_timeout_ms

(optional, integer) If a watched thread has been nonresponsive for this many milliseconds assume a programming error and kill the entire Envoy process. Set to 0 to disable kill behavior. If not specified the default is 0 (disabled).

watchdog_multikill_timeout_ms

(optional, integer) If at least two watched threads have been nonresponsive for at least this many milliseconds assume a true deadlock and kill the entire Envoy process. Set to 0 to disable this behavior. If not specified the default is 0 (disabled).

tracing

(optional, object) Configuration for an external tracing provider. If not specified, no tracing will be performed.

rate_limit_service

(optional, object) Configuration for an external rate limit service provider. If not specified, any calls to the rate limit service will immediately return success.

runtime

(optional, object) Configuration for the runtime configuration provider. If not specified, a “null” provider will be used which will result in all defaults being used.