Administration interface¶
Envoy exposes a local administration interface that can be used to query and modify different aspects of the server:
Attention
The administration interface in its current form both allows destructive operations to be performed (e.g., shutting down the server) as well as potentially exposes private information (e.g., stats, cluster names, cert info, etc.). It is critical that access to the administration interface is only allowed via a secure network. It is also critical that hosts that access the administration interface are only attached to the secure network (i.e., to avoid CSRF attacks). This involves setting up an appropriate firewall or optimally only allowing access to the administration listener via localhost. This can be accomplished with a v2 configuration like the following:
admin:
access_log_path: /tmp/admin_access.log
address:
socket_address: { address: 127.0.0.1, port_value: 9901 }
In the future additional security options will be added to the administration interface. This work is tracked in this issue.
-
GET
/
¶ Render an HTML home page with a table of links to all available options.
-
GET
/help
¶ Print a textual table of all available options.
-
GET
/certs
¶ List out all loaded TLS certificates, including file name, serial number, and days until expiration.
-
GET
/clusters
¶ List out all configured cluster manager clusters. This information includes all discovered upstream hosts in each cluster along with per host statistics. This is useful for debugging service discovery issues.
- Cluster manager information
- Cluster wide information
- circuit breakers settings for all priority settings.
- Information about outlier detection if a detector is installed. Currently
success rate average,
and ejection threshold
are presented. Both of these values could be
-1
if there was not enough data to calculate them in the last interval. added_via_api
flag –false
if the cluster was added via static configuration,true
if it was added via the CDS api.
- Per host statistics
Name Type Description cx_total Counter Total connections cx_active Gauge Total active connections cx_connect_fail Counter Total connection failures rq_total Counter Total requests rq_timeout Counter Total timed out requests rq_success Counter Total requests with non-5xx responses rq_error Counter Total requests with 5xx responses rq_active Gauge Total active requests healthy String The health status of the host. See below weight Integer Load balancing weight (1-100) zone String Service zone canary Boolean Whether the host is a canary success_rate Double Request success rate (0-100). -1 if there was not enough request volume in the interval to calculate it - Host health status
A host is either healthy or unhealthy because of one or more different failing health states. If the host is healthy the
healthy
output will be equal to healthy.If the host is not healthy, the
healthy
output will be composed of one or more of the following strings:/failed_active_hc: The host has failed an active health check.
/failed_outlier_check: The host has failed an outlier detection check.
-
GET
/cpuprofiler
¶ Enable or disable the CPU profiler. Requires compiling with gperftools.
-
GET
/healthcheck/fail
¶ Fail inbound health checks. This requires the use of the HTTP health check filter. This is useful for draining a server prior to shutting it down or doing a full restart. Invoking this command will universally fail health check requests regardless of how the filter is configured (pass through, etc.).
-
GET
/healthcheck/ok
¶ Negate the effect of
GET /healthcheck/fail
. This requires the use of the HTTP health check filter.
-
GET
/hot_restart_version
¶
-
GET
/logging
¶ Enable/disable different logging levels on different subcomponents. Generally only used during development.
-
GET
/quitquitquit
¶ Cleanly exit the server.
-
GET
/reset_counters
¶ Reset all counters to zero. This is useful along with
GET /stats
during debugging. Note that this does not drop any data sent to statsd. It just effects local output of theGET /stats
command.
-
GET
/routes?route_config_name=<name>
¶ This endpoint is only available if envoy has HTTP routes configured via RDS. The endpoint dumps all the configured HTTP route tables, or only ones that match the
route_config_name
query, if a query is specified.
-
GET
/server_info
¶ Outputs information about the running server. Sample output looks like:
envoy 267724/RELEASE live 1571 1571 0
The fields are:
- Process name
- Compiled SHA and build type
- Health check state (live or draining)
- Current hot restart epoch uptime in seconds
- Total uptime in seconds (across all hot restarts)
- Current hot restart epoch
-
GET
/stats
¶ Outputs all statistics on demand. This includes only counters and gauges. Histograms are not output as Envoy currently has no built in histogram support and relies on statsd for aggregation. This command is very useful for local debugging. See here for more information.
-
GET
/stats?format=json
¶
Outputs /stats in JSON format. This can be used for programmatic access of stats.
-
GET
/stats?format=prometheus
¶
Outputs /stats in Prometheus v0.0.4 format. This can be used to integrate with a Prometheus server. Currently, only counters and gauges are output. Histograms will be output in a future update.
-