envoyproxy/envoy

Admin

The admin server is the HTTP debug console embedded in every Envoy process. Operators use it for diagnostics, runtime overrides, profiling, and graceful shutdown. It runs on the main thread, exposes a small HTTP/1 server, and dispatches each request to a handler. Implementation in source/server/admin/.

Purpose

Expose a uniform HTTP interface for everything an operator needs to inspect or change at runtime.
Run on a dedicated address so it can be ACL'd off from production traffic.
Be available even when the configured listeners are misbehaving (it lives on the main thread, not workers).
Be optional at compile time (ENVOY_ADMIN_FUNCTIONALITY macro). Some embedded users build Envoy without it.

The user-facing reference is at envoyproxy.io/docs/envoy/latest/operations/admin.

Layout

source/server/admin/
├── admin.{h,cc}                  # The Admin class — server, dispatcher, registration
├── admin_filter.{h,cc}           # Internal HTTP filter that runs on admin requests
├── admin_html_util.{h,cc}        # HTML rendering helpers
├── config_dump_handler.{h,cc}    # /config_dump
├── clusters_handler.{h,cc}       # /clusters
├── listeners_handler.{h,cc}      # /listeners
├── logs_handler.{h,cc}           # /logging
├── profiling_handler.{h,cc}      # /cpuprofiler, /heapprofiler, /tcmalloc, ...
├── prometheus_stats.{h,cc}       # /stats?format=prometheus
├── runtime_handler.{h,cc}        # /runtime, /runtime_modify
├── server_cmd_handler.{h,cc}     # /quitquitquit, /healthcheck/{fail,ok}
├── server_info_handler.{h,cc}    # /server_info, /ready, /memory
├── stats_handler.{h,cc}          # /stats and friends
├── stats_render.{h,cc}, stats_html_render.{h,cc}
├── stats_request.{h,cc}, stats_params.{h,cc}
├── init_dump_handler.{h,cc}      # /init_dump
├── config_tracker_impl.{h,cc}    # Registry for config_dump entries
└── html/                         # Static HTML/CSS for the admin UI

Key abstractions

Type	File	Role
`Server::AdminImpl`	`admin.h`	The HTTP server: hosts handlers, owns the listener, dispatches requests.
`Server::Admin::HandlerCb`	(same)	Function signature for handlers; takes a path/headers/buffer/response_headers/admin_stream and returns a status code.
`AdminFilter`	`admin_filter.h`	The custom HTTP filter run on admin requests.
`ConfigTracker`	`envoy/server/config_tracker.h`	Subsystems register `getConfigDump` callbacks here.
`StatsRequest`	`stats_request.h`	Streams large `/stats` responses chunk-by-chunk.

Endpoint catalogue

The full list is registered in AdminImpl::AdminImpl. The most-used:

Path	Handler	What it does
`GET /`	inline	Returns the HTML index.
`GET /server_info`	`server_info_handler`	Version, build flags, uptime, server state.
`GET /ready`	`server_info_handler`	200 once init is complete.
`GET /memory`	`server_info_handler`	tcmalloc / mimalloc / generic malloc stats.
`GET /stats`	`stats_handler`	Stat dump (text, JSON, or Prometheus).
`GET /stats/prometheus`	`prometheus_stats`	Prometheus exposition format.
`GET /clusters`	`clusters_handler`	Per-cluster, per-host status.
`GET /listeners`	`listeners_handler`	Configured listeners.
`GET /config_dump`	`config_dump_handler`	Combined Bootstrap, LDS, CDS, RDS, SDS, RTDS view.
`GET /init_dump`	`init_dump_handler`	InitManager state for diagnosing why server isn't ready.
`POST /logging`	`logs_handler`	Set log levels (`?level=X` or `?paths=a:debug,b:trace`).
`GET /runtime`, `POST /runtime_modify`	`runtime_handler`	Inspect / override runtime.
`POST /reset_counters`	`stats_handler`	Zero counters.
`POST /quitquitquit`	`server_cmd_handler`	Graceful shutdown.
`POST /drain_listeners`	`listeners_handler`	Begin listener drain (used by hot restart and rolling updates).
`POST /healthcheck/fail` / `/ok`	`server_cmd_handler`	Fail/recover the health-check filter.
`POST /cpuprofiler`	`profiling_handler`	Start/stop `gperftools` CPU profiling.
`POST /heapprofiler`	`profiling_handler`	Start/stop `tcmalloc` heap profiling.
`POST /heap_dump`	`profiling_handler`	Take a heap snapshot.
`GET /stats/recentlookups`	`stats_handler`	Diagnose hot-path stat allocations.
`GET /contention`	`profiling_handler`	Mutex contention sampling (build-time gated).
`GET /hot_restart_version`	inline	Hot-restart RPC ABI version.

Streaming responses

Endpoints that produce large outputs (/stats, /clusters, /config_dump) use chunked streaming via Admin::Request (envoy/server/admin.h) so the response is yielded one chunk at a time without holding the entire payload in memory. The MainCommonBase::adminRequest pair (sync and streaming) in source/exe/main_common.cc lets in-process consoles (e.g. an embedding application) call admin without going through the network.

ConfigTracker

Subsystems register dump callbacks with ConfigTrackerImpl (config_tracker_impl.cc). At /config_dump time the handler walks the registry in a deterministic order:

Bootstrap → static listeners → LDS dynamic listeners → static clusters → CDS dynamic clusters → RDS route configurations → static secrets → SDS dynamic secrets → static ECDS → dynamic ECDS → RTDS → scoped_routes.

Each subsystem owns its own callback and yields its serialised state.

HTML UI

The admin server can serve an HTML UI for stats and config dumps. It's optional (compiled out via admin_no_html.cc for builds that want only the API). Static assets live in source/server/admin/html/.

Security

Admin is intentionally not on the same address as the data plane. The bootstrap controls bind address, ACL via interface routing, and TLS:

admin:
  address: { socket_address: { address: 127.0.0.1, port_value: 9901 } }

Admin can also be disabled entirely. POST /quitquitquit is potentially dangerous; production deployments either lock it down by network policy or disable handlers via --admin-allow-list.

Integration points

Server lifecycle. Constructed by InstanceImpl after stats and runtime are ready.
All systems — every subsystem with operator-relevant state registers a config-dump callback.
Stats — admin owns /stats and /stats/prometheus and reads from the central store.
Runtime — admin layer overrides write here.
Hot restart — POST /drain_listeners is part of the hot-restart handoff sequence.

Entry points for modification

Adding a new endpoint: add a handler class, register it in AdminImpl::AdminImpl.
Modifying an existing endpoint's response: edit the relevant *_handler.cc.
Adding a config dump source: implement ConfigTracker::Cb and register with tracker.add(name, cb).