Envoy admin interface

The optional admin interface provided by Envoy allows you to view configuration and statistics, change the behaviour of the server, and tap traffic according to specific filter rules.

Note

This guide provides configuration information, and some basic examples of using a couple of the admin endpoints.

See the admin docs for information on all of the available endpoints.

Requirements

Some of the examples below make use of the jq tool to parse the output from the admin server.

admin

The admin message is required to enable and configure the administration server.

The address key specifies the listening address which in the demo configuration is 0.0.0.0:9901.

In this example, the logs are simply discarded.

  1. admin:
  2.   address:
  3.     socket_address:
  4.       address: 0.0.0.0
  5.       port_value: 9901

Warning

The Envoy admin endpoint can expose private information about the running service, allows modification of runtime settings and can also be used to shut the server down.

As the endpoint is not authenticated it is essential that you limit access to it.

You may wish to restrict the network address the admin server listens to in your own deployment as part of your strategy to limit access to this endpoint.

stat_prefix

The Envoy HttpConnectionManager must be configured with stat_prefix.

This provides a key that can be filtered when querying the stats interface as shown below

In the envoy-demo.yaml the listener is configured with the stat_prefix of ingress_http.

  1. static_resources:
  3.   listeners:
  4.   - name: listener_0
  5.     address:
  6.       socket_address:
  7.         address: 0.0.0.0
  8.         port_value: 10000
  9.     filter_chains:
  10.     - filters:
  11.       - name: envoy.filters.network.http_connection_manager
  12.         typed_config:
  13.           "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
  14.           stat_prefix: ingress_http
  15.           access_log:
  16.           - name: envoy.access_loggers.stdout
  17.             typed_config:
  18.               "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
  19.           http_filters:
  20.           - name: envoy.filters.http.router
  21.           route_config:
  22.             name: local_route
  23.             virtual_hosts:
  24.             - name: local_service
  25.               domains: ["*"]
  26.               routes:
  27.               - match:
  28.                   prefix: "/"
  29.                 route:

Admin endpoints: config_dump

The config_dump endpoint returns Envoy’s runtime configuration in json format.

The following command allows you to see the types of configuration available:

  1. $ curl -s http://localhost:9901/config_dump | jq -r '.configs[] | .["@type"]'
  2. type.googleapis.com/envoy.admin.v3.BootstrapConfigDump
  3. type.googleapis.com/envoy.admin.v3.ClustersConfigDump
  4. type.googleapis.com/envoy.admin.v3.ListenersConfigDump
  5. type.googleapis.com/envoy.admin.v3.ScopedRoutesConfigDump
  6. type.googleapis.com/envoy.admin.v3.RoutesConfigDump
  7. type.googleapis.com/envoy.admin.v3.SecretsConfigDump

To view the socket_address of the first dynamic_listener currently configured, you could:

  1. $ curl -s http://localhost:9901/config_dump?resource=dynamic_listeners | jq '.configs[0].active_state.listener.address'
  2. {
  3.   "socket_address": {
  4.     "address": "0.0.0.0",
  5.     "port_value": 10000
  6.   }
  7. }

Note

See the reference section for config_dump for further information on available parameters and responses.

Tip

Enabling the admin interface with dynamic configuration can be particularly useful as it allows you to use the config_dump endpoint to see how Envoy is configured at a particular point in time.

Admin endpoints: stats

The admin stats endpoint allows you to retrieve runtime information about Envoy.

The stats are provided as key: value pairs, where the keys use a hierarchical dotted notation, and the values are one of counter, histogram or gauge types.

To see the top-level categories of stats available, you can:

  1. $ curl -s http://localhost:9901/stats | cut -d. -f1 | sort | uniq
  2. cluster
  3. cluster_manager
  4. filesystem
  5. http
  6. http1
  7. listener
  8. listener_manager
  9. main_thread
  10. runtime
  11. server
  12. vhost
  13. workers

The stats endpoint accepts a filter argument, which is evaluated as a regular expression:

  1. $ curl -s http://localhost:9901/stats?filter='^http\.ingress_http'
  2. http.ingress_http.downstream_cx_active: 0
  3. http.ingress_http.downstream_cx_delayed_close_timeout: 0
  4. http.ingress_http.downstream_cx_destroy: 3
  5. http.ingress_http.downstream_cx_destroy_active_rq: 0
  6. http.ingress_http.downstream_cx_destroy_local: 0
  7. http.ingress_http.downstream_cx_destroy_local_active_rq: 0
  8. http.ingress_http.downstream_cx_destroy_remote: 3
  9. http.ingress_http.downstream_cx_destroy_remote_active_rq: 0
  10. http.ingress_http.downstream_cx_drain_close: 0
  11. http.ingress_http.downstream_cx_http1_active: 0
  12. http.ingress_http.downstream_cx_http1_total: 3
  13. http.ingress_http.downstream_cx_http2_active: 0
  14. http.ingress_http.downstream_cx_http2_total: 0
  15. http.ingress_http.downstream_cx_http3_active: 0
  16. http.ingress_http.downstream_cx_http3_total: 0
  17. http.ingress_http.downstream_cx_idle_timeout: 0
  18. http.ingress_http.downstream_cx_max_duration_reached: 0
  19. http.ingress_http.downstream_cx_overload_disable_keepalive: 0
  20. http.ingress_http.downstream_cx_protocol_error: 0
  21. http.ingress_http.downstream_cx_rx_bytes_buffered: 0
  22. http.ingress_http.downstream_cx_rx_bytes_total: 250
  23. http.ingress_http.downstream_cx_ssl_active: 0
  24. http.ingress_http.downstream_cx_ssl_total: 0
  25. http.ingress_http.downstream_cx_total: 3
  26. http.ingress_http.downstream_cx_tx_bytes_buffered: 0
  27. http.ingress_http.downstream_cx_tx_bytes_total: 1117
  28. http.ingress_http.downstream_cx_upgrades_active: 0
  29. http.ingress_http.downstream_cx_upgrades_total: 0
  30. http.ingress_http.downstream_flow_control_paused_reading_total: 0
  31. http.ingress_http.downstream_flow_control_resumed_reading_total: 0
  32. http.ingress_http.downstream_rq_1xx: 0
  33. http.ingress_http.downstream_rq_2xx: 3
  34. http.ingress_http.downstream_rq_3xx: 0
  35. http.ingress_http.downstream_rq_4xx: 0
  36. http.ingress_http.downstream_rq_5xx: 0
  37. http.ingress_http.downstream_rq_active: 0
  38. http.ingress_http.downstream_rq_completed: 3
  39. http.ingress_http.downstream_rq_http1_total: 3
  40. http.ingress_http.downstream_rq_http2_total: 0
  41. http.ingress_http.downstream_rq_http3_total: 0
  42. http.ingress_http.downstream_rq_idle_timeout: 0
  43. http.ingress_http.downstream_rq_max_duration_reached: 0
  44. http.ingress_http.downstream_rq_non_relative_path: 0
  45. http.ingress_http.downstream_rq_overload_close: 0
  46. http.ingress_http.downstream_rq_response_before_rq_complete: 0
  47. http.ingress_http.downstream_rq_rx_reset: 0
  48. http.ingress_http.downstream_rq_timeout: 0
  49. http.ingress_http.downstream_rq_too_large: 0
  50. http.ingress_http.downstream_rq_total: 3
  51. http.ingress_http.downstream_rq_tx_reset: 0
  52. http.ingress_http.downstream_rq_ws_on_non_ws_route: 0
  53. http.ingress_http.no_cluster: 0
  54. http.ingress_http.no_route: 0
  55. http.ingress_http.passthrough_internal_redirect_bad_location: 0
  56. http.ingress_http.passthrough_internal_redirect_no_route: 0
  57. http.ingress_http.passthrough_internal_redirect_predicate: 0
  58. http.ingress_http.passthrough_internal_redirect_too_many_redirects: 0
  59. http.ingress_http.passthrough_internal_redirect_unsafe_scheme: 0
  60. http.ingress_http.rq_direct_response: 0
  61. http.ingress_http.rq_redirect: 0
  62. http.ingress_http.rq_reset_after_downstream_response_started: 0
  63. http.ingress_http.rq_total: 3
  64. http.ingress_http.rs_too_large: 0
  65. http.ingress_http.tracing.client_enabled: 0
  66. http.ingress_http.tracing.health_check: 0
  67. http.ingress_http.tracing.not_traceable: 0
  68. http.ingress_http.tracing.random_sampling: 0
  69. http.ingress_http.tracing.service_forced: 0
  70. http.ingress_http.downstream_cx_length_ms: P0(nan,2.0) P25(nan,2.075) P50(nan,3.05) P75(nan,17.25) P90(nan,17.7) P95(nan,17.85) P99(nan,17.97) P99.5(nan,17.985) P99.9(nan,17.997) P100(nan,18.0)
  71. http.ingress_http.downstream_rq_time: P0(nan,1.0) P25(nan,1.075) P50(nan,2.05) P75(nan,16.25) P90(nan,16.7) P95(nan,16.85) P99(nan,16.97) P99.5(nan,16.985) P99.9(nan,16.997) P100(nan,17.0)

You can also pass a format argument, for example to return json:

  1. $ curl -s "http://localhost:9901/stats?filter=http.ingress_http.rq&format=json" | jq '.stats'
  1. [
  2.   {
  3.     "value": 0,
  4.     "name": "http.ingress_http.rq_direct_response"
  5.   },
  6.   {
  7.     "value": 0,
  8.     "name": "http.ingress_http.rq_redirect"
  9.   },
  10.   {
  11.     "value": 0,
  12.     "name": "http.ingress_http.rq_reset_after_downstream_response_started"
  13.   },
  14.   {
  15.     "value": 3,
  16.     "name": "http.ingress_http.rq_total"
  17.   }
  18. ]

Envoy admin web UI

Envoy also has a web user interface that allows you to view and modify settings and statistics.

Point your browser to http://localhost:9901.

../../_images/envoy-admin.png