envoyproxy/envoy

Server lifecycle

Server::InstanceImpl is the top-level object that orchestrates everything else inside an Envoy process. This page covers what happens between main() and a steady-state running server, and what happens during shutdown.

The entry path

main() in source/exe/main.cc
   └─> MainCommon::main() in source/exe/main_common.cc
         └─> MainCommonBase::run() runs the server's dispatcher
               └─> InstanceBase::run() in source/server/server.cc
                     ├─> initialize() (build subsystems)
                     ├─> RunHelper (await init, signals)
                     └─> dispatcher_->run(RunUntilExit)

The implementation is split across:

source/exe/main.cc — thin platform-specific entrypoint.
source/exe/main_common.cc and stripped_main_base.cc — non-platform-specific wiring of Server::InstanceImpl from command-line options and a ComponentFactory.
source/server/server.cc and source/server/server.h — InstanceBase (the lifecycle) and InstanceImpl (the production subclass).

What `InstanceBase` owns

The class is large because the server is the central registry. From source/server/server.h:

Subsystem	Member	Built by
Cluster manager	`cluster_manager_factory_`, `cluster_manager_` (lazy)	`source/common/upstream/cluster_manager_impl.cc`
Listener manager	`listener_manager_`	`source/common/listener_manager/`
Admin	`admin_` (gated on `ENVOY_ADMIN_FUNCTIONALITY`)	`source/server/admin/admin.cc`
Runtime	`runtime_singleton_`	`source/common/runtime/runtime_impl.cc`
Stats store	`stats_store_` (passed in)	`source/common/stats/`
Drain manager	`drain_manager_`	`source/server/drain_manager_impl.cc`
Overload manager	`overload_manager_` + `null_overload_manager_`	`source/server/overload_manager_impl.cc`
Watchdog	`main_thread_guard_dog_`, `worker_guard_dog_`	`source/server/guarddog_impl.cc`
Hot restart	`restarter_` (passed in)	`source/server/hot_restart_impl.cc`
Init manager	`init_manager_` (passed in)	`source/common/init/manager_impl.cc`
Secret manager	`secret_manager_`	`source/common/secret/secret_manager_impl.cc`
ThreadLocal	`tls_` (passed in)	`source/common/thread_local/thread_local_impl.cc`
Hot restart RPC	`hot_restart_*`	inside the same module
TLS context manager	`ssl_context_manager_`	`source/common/tls/`
Tracer	`http_tracer_`	tracer extension factory

These are the things whose pages you'll find under systems.

Bootstrap flow

flowchart TD
    Start([main]) --> Args[Parse argv via OptionsImpl]
    Args --> Boot[Load bootstrap.yaml<br/>InstanceUtil::loadBootstrapConfig]
    Boot --> Validate{--mode validate?}
    Validate -->|yes| ExitVal[Exit after validation]
    Validate -->|no| HotRestart[HotRestart::initialize<br/>shared memory]
    HotRestart --> Build[Build subsystems<br/>order: stats, runtime, secrets,<br/>cluster mgr, admin, overload mgr,<br/>tracing, listener mgr, workers]
    Build --> WaitInit[InitManager::initialize<br/>resolve all init targets]
    WaitInit --> StartWorkers[Start workers + accept]
    StartWorkers --> Run[dispatcher_-&gt;run]
    Run --> Signal[SIGTERM / quitquitquit]
    Signal --> Drain[drainListeners + shutdown]
    Drain --> Stop([Process exit])

The construction order matters. Stats and runtime come first because everything else uses them. The listener manager is built last because its listeners depend on clusters. After InitManager::initialize succeeds (xDS subscriptions delivered the first config, certs loaded, etc.), the server signals RunHelper and the workers start accepting connections.

InitManager

Init::Manager (source/common/init/manager_impl.cc) is the protocol used to gate "ready to serve". Each subsystem registers init targets with the manager; each target is a callback that completes when that piece is initialised. The manager calls each target's initialize() and waits for completion before declaring the parent ready.

Init managers are nested: the server has a top-level one; each cluster, listener, and route-config has its own that feeds upward. Used widely:

An EDS cluster registers a target that completes when the first endpoint update arrives.
An SDS-backed listener registers a target that completes when the first cert arrives.
The HCM filter chain registers a target if any per-filter ECDS subscription is in use.

Without this, listeners could start accepting connections before they had certs, and clusters could pick hosts before the first endpoint list arrived.

DrainManager

Server::DrainManager (source/server/drain_manager_impl.cc) implements the multi-stage drain sequence:

Drain start. Bootstrap.drain_strategy is consulted; the manager schedules a graceful drain over drain_time_s (typically 600s).
Listener drain. Connections are no longer accepted; Connection: close headers are added; HTTP/2 GOAWAY is sent.
Hard shutdown. Remaining connections are closed.

The drain manager is shared by:

Hot restart parent. Drains in response to the new child taking over.
Listener removal via LDS. A removed listener drains its existing connections.
POST /drain_listeners admin endpoint.

OverloadManager

Server::OverloadManagerImpl (source/server/overload_manager_impl.cc) is the framework for back-pressure. It hosts:

A set of resource monitors (source/extensions/resource_monitors/) — fixed_heap, injected_resource, cgroup_memory, downstream_connections, etc.
A set of overload actions keyed by name — envoy.overload_actions.shrink_heap, envoy.overload_actions.stop_accepting_requests, …
A trigger map that turns monitor pressure into action state.

Workers subscribe to action callbacks; when pressure crosses a threshold, the manager broadcasts a state change to all workers. Each worker reacts by rejecting connections, resetting expensive streams, closing idle connections, etc.

GuardDog

Server::GuardDogImpl (source/server/guarddog_impl.cc) is a separate thread that periodically inspects each registered watchdog (one per worker plus one for the main thread). Every dispatcher pulse "pets" its watchdog; if a dispatcher hasn't pet its watchdog within miss (typically 200ms) the GuardDog logs; within megamiss (typically 1s) it abort()s the process.

This is the safety net that catches accidental blocking calls or busy loops on a worker.

Lifecycle notifications

ServerLifecycleNotifier (interface in envoy/server/lifecycle_notifier.h, implemented by InstanceBase) lets extensions register callbacks for stages: PostInit, BeforeShutdown, ShutdownPipeline. Filters and bootstrap extensions use it to do their own setup/teardown.

Validate mode

--mode validate (or init_only) runs the bootstrap loader and creates a ValidationInstance (source/server/config_validation/) that constructs the configuration tree but never starts workers or binds sockets. It is used by envoy --mode validate -c bootstrap.yaml for offline config validation in CI pipelines.

Key source files

File	Role
`source/exe/main.cc`	`int main(...)`
`source/exe/main_common.cc`	`MainCommon` wrapper
`source/server/server.h`	`InstanceBase`, `InstanceImpl` declarations
`source/server/server.cc`	Lifecycle implementation
`source/server/options_impl.cc`	Command-line option parsing
`source/server/drain_manager_impl.cc`	Drain sequence
`source/server/overload_manager_impl.cc`	Overload framework
`source/server/guarddog_impl.cc`	Watchdog
`source/common/init/manager_impl.cc`	InitManager