The runtime configuration specifies the location of the local file system tree that contains re-loadable configuration elements. If runtime is not configured, a “null” provider is used which has the effect of using all defaults built into the code.

File system layout

Various sections of the configuration guide describe the runtime settings that are available. For example, here are the runtime settings for upstream clusters.

Assume that the folder /srv/runtime/v1 points to the actual file system path where global runtime configurations are stored. The following would be a typical configuration setting for runtime:

  • symlink_root: /srv/runtime/current
  • subdirectory: envoy
  • override_subdirectory: envoy_override

Where /srv/runtime/current is a symbolic link to /srv/runtime/v1.

Each ‘.’ in a runtime key indicates a new directory in the hierarchy, rooted at symlink_root + subdirectory. For example, the health_check.min_interval key would have the following full file system path (using the symbolic link):


The terminal portion of a path is the file. The contents of the file constitute the runtime value. When reading numeric values from a file, spaces and new lines will be ignored.

The override_subdirectory is used along with the --service-cluster CLI option. Assume that --service-cluster has been set to my-cluster. Envoy will first look for the health_check.min_interval key in the following full file system path:


If found, the value will override any value found in the primary lookup path. This allows the user to customize the runtime values for individual clusters on top of global defaults.


Lines starting with # as the first character are treated as comments.

Comments can be used to provide context on an existing value. Comments are also useful in an otherwise empty file to keep a placeholder for deployment in a time of need.


The file system runtime provider emits some statistics in the runtime. namespace.

Name Type Description
load_error Counter Total number of load attempts that resulted in an error
override_dir_not_exists Counter Total number of loads that did not use an override directory
override_dir_exists Counter Total number of loads that did use an override directory
load_success Counter Total number of load attempts that were successful
num_keys Gauge Number of keys currently loaded