Runtime

The runtime is Envoy's key/value flag store. Code consults it at request time for feature flags, percentage gates, deprecation guards, and gradual rollout. It lives in source/common/runtime/.

Purpose

• Provide a uniform Runtime::Loader interface for reading bool / int / string / fractional features.
• Layer multiple sources (static defaults, admin overrides, RTDS) with last-write-wins semantics per key.
• Wire features to the admin interface for live overrides.
• Drive the deprecation lifecycle: most "new behaviour" lands behind a runtime guard that defaults true and is removed after one release cycle.

Layout

source/common/runtime/
├── runtime_impl.{h,cc}        # The Loader and Snapshot
├── runtime_features.{h,cc}    # Compile-time-registered feature flags + defaults
└── runtime_keys.{h,cc}        # Reusable runtime key strings

Key abstractions

Type	File	Role
Runtime::Loader	envoy/runtime/runtime.h	Public interface — what code calls.
Runtime::Snapshot	(same)	Immutable snapshot of all layers' merged values; what Loader returns.
LoaderImpl	runtime_impl.h	Production implementation; manages layers and TLS slots.
RuntimeFeatures	runtime_features.h	Compile-time registry of bool features and their defaults.
RuntimeKeys	runtime_keys.h	Canonical names for cross-cutting keys.

Layers

LoaderImpl merges multiple sources, in order, with later layers winning:

1. Static layer — values from Bootstrap.layered_runtime.
2. Disk layer — values from a local filesystem directory if configured (legacy).
3. Admin layer — values set via POST /runtime_modify.
4. RTDS layer(s) — runtime resources delivered over xDS.

A snapshot is rebuilt whenever any layer changes. Snapshots are pushed to all workers via TLS slots (see threading model) so the data plane reads don't lock.

Reading from code

// Boolean feature flag (preferred for new code)
if (Runtime::runtimeFeatureEnabled("envoy.reloadable_features.my_change")) {
  // new behaviour
}

// Read with a default
const uint64_t threshold = runtime_.snapshot().getInteger(
    "envoy.config.threshold", 1024);

// Fractional rollout (sometimes "%" gate)
if (runtime_.snapshot().featureEnabled("my_feature_rollout", 50 /* %*/)) {
  // 50% of requests
}

Runtime::runtimeFeatureEnabled reads a global singleton and is the most common entry point. The full snapshot API is on the Runtime::Snapshot interface.

The feature registry

runtime_features.cc is a long, alphabetised list of named features and their defaults:

RUNTIME_GUARD(envoy_reloadable_features_some_feature);
FALSE_RUNTIME_GUARD(envoy_reloadable_features_dangerous_feature);
LEGACY_RUNTIME_GUARD(envoy_reloadable_features_old_thing);

RUNTIME_GUARD defaults to true; FALSE_RUNTIME_GUARD defaults to false. New code goes behind a RUNTIME_GUARD so operators can disable it; if no one disables it for a release cycle, the guard is removed.

RTDS

The Runtime Discovery Service (RTDS, in api/envoy/service/runtime/v3/rtds.proto) lets a control plane push runtime values dynamically. Each RTDS layer maps to one xDS subscription. The control plane can roll out percentage gates without redeploying Envoy.

Stats

Runtime emits stats:

• runtime.load_success — number of successful layer loads.
• runtime.load_error — number of malformed layers.
• runtime.override_dir_exists — disk layer used.
• runtime.deprecated_feature_use — incremented every time a deprecated feature is used.

The deprecated-feature counter is what drives the deprecation policy.

Admin endpoints

• GET /runtime — pretty-print all current values per layer.
• POST /runtime_modify?key=value — push to the admin layer.
• POST /runtime_revert?keys=key1,key2 — remove from the admin layer.

Integration points

• All extensions and core code consult runtime via the loader.
• xDS — RTDS subscription is one source.
• Admin — operator overrides.
• Tests — Test::Runtime (in test/test_common/) provides a fake loader for unit tests.

Entry points for modification

• Adding a new feature flag: add a RUNTIME_GUARD line in runtime_features.cc and gate code with Runtime::runtimeFeatureEnabled.
• Adding a new layer source: implement a RuntimeFactory and register it.
• Modifying snapshot semantics: read LoaderImpl::loadNewSnapshot in runtime_impl.cc.

See also

• Admin — operator override paths.
• xDS configuration — RTDS as an xDS API.
• Development workflow — how to add a new runtime guard.