diff --git a/docs/root/start/quick-start/_include/envoy-demo.yaml b/docs/root/start/quick-start/_include/envoy-demo.yaml index b3697360e1208..99bb743a97c5a 100644 --- a/docs/root/start/quick-start/_include/envoy-demo.yaml +++ b/docs/root/start/quick-start/_include/envoy-demo.yaml @@ -46,10 +46,3 @@ static_resources: typed_config: "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext sni: www.envoyproxy.io - -admin: - access_log_path: /dev/null - address: - socket_address: - address: 0.0.0.0 - port_value: 9901 diff --git a/docs/root/start/quick-start/admin.rst b/docs/root/start/quick-start/admin.rst new file mode 100644 index 0000000000000..1071c5e4c6b3a --- /dev/null +++ b/docs/root/start/quick-start/admin.rst @@ -0,0 +1,256 @@ +.. _start_quick_start_admin: + +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 :ref:`admin docs ` for information on all of the available endpoints. + +.. admonition:: Requirements + + Some of the examples below make use of the `jq `_ tool to parse the output + from the admin server. + +.. _start_quick_start_admin_config: + +``admin`` +--------- + +The :ref:`admin message ` is required to enable and configure +the administration server. + +The ``address`` key specifies the listening :ref:`address ` +which in the demo configuration is ``0.0.0.0:9901``. + +You must set the :ref:`access_log_path ` to +specify where to send admin access logs. + +In this example, the logs are simply discarded. + +.. code-block:: yaml + :emphasize-lines: 2, 5-6 + + admin: + access_log_path: /dev/null + address: + socket_address: + address: 0.0.0.0 + port_value: 9901 + +.. warning:: + + The Envoy admin endpoint can expose private information about the running service, and + can also be used to shut it 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 +:ref:`HttpConnectionManager ` +must be configured with +:ref:`stat_prefix `. + +This provides a key that can be filtered when querying the stats interface +:ref:`as shown below ` + +In the :download:`envoy-demo.yaml <_include/envoy-demo.yaml>` the listener is configured with the +:ref:`stat_prefix ` +of ``ingress_http``. + +.. literalinclude:: _include/envoy-demo.yaml + :language: yaml + :linenos: + :lines: 1-29 + :emphasize-lines: 13-14 + +.. _start_quick_start_admin_config_dump: + +Admin endpoints: ``config_dump`` +-------------------------------- + +The :ref:`config_dump ` endpoint returns Envoy's runtime +configuration in ``json`` format. + +The following command allows you to see the types of configuration available: + +.. code-block:: console + + $ curl -s http://localhost:9901/config_dump | jq -r '.configs[] | .["@type"]' + type.googleapis.com/envoy.admin.v3.BootstrapConfigDump + type.googleapis.com/envoy.admin.v3.ClustersConfigDump + type.googleapis.com/envoy.admin.v3.ListenersConfigDump + type.googleapis.com/envoy.admin.v3.ScopedRoutesConfigDump + type.googleapis.com/envoy.admin.v3.RoutesConfigDump + type.googleapis.com/envoy.admin.v3.SecretsConfigDump + +To view the :ref:`socket_address ` of the first +:ref:`dynamic_listener ` currently configured, +you could: + +.. code-block:: console + + $ curl -s http://localhost:19000/config_dump?resource=dynamic_listeners | jq '.configs[0].active_state.listener.address' + { + "socket_address": { + "address": "0.0.0.0", + "port_value": 10000 + } + } + +.. note:: + + See the reference section for :ref:`config_dump ` for further information + on available parameters and responses. + +.. tip:: + + Enabling the :ref:`admin ` interface with + dynamic configuration can be particularly useful as it allows you to use the + :ref:`config_dump ` endpoint to see how Envoy is configured at + a particular point in time. + +.. _start_quick_start_admin_stats: + +Admin endpoints: ``stats`` +-------------------------- + +The :ref:`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: + +.. code-block:: console + + $ curl -s http://localhost:9901/stats | cut -d. -f1 | sort | uniq + cluster + cluster_manager + filesystem + http + http1 + listener + listener_manager + main_thread + runtime + server + vhost + workers + +The stats endpoint accepts a :ref:`filter ` argument, which +is evaluated as a regular expression: + +.. code-block:: console + + $ curl -s http://localhost:19000/stats?filter='^http\.ingress_http' + http.ingress_http.downstream_cx_active: 0 + http.ingress_http.downstream_cx_delayed_close_timeout: 0 + http.ingress_http.downstream_cx_destroy: 3 + http.ingress_http.downstream_cx_destroy_active_rq: 0 + http.ingress_http.downstream_cx_destroy_local: 0 + http.ingress_http.downstream_cx_destroy_local_active_rq: 0 + http.ingress_http.downstream_cx_destroy_remote: 3 + http.ingress_http.downstream_cx_destroy_remote_active_rq: 0 + http.ingress_http.downstream_cx_drain_close: 0 + http.ingress_http.downstream_cx_http1_active: 0 + http.ingress_http.downstream_cx_http1_total: 3 + http.ingress_http.downstream_cx_http2_active: 0 + http.ingress_http.downstream_cx_http2_total: 0 + http.ingress_http.downstream_cx_http3_active: 0 + http.ingress_http.downstream_cx_http3_total: 0 + http.ingress_http.downstream_cx_idle_timeout: 0 + http.ingress_http.downstream_cx_max_duration_reached: 0 + http.ingress_http.downstream_cx_overload_disable_keepalive: 0 + http.ingress_http.downstream_cx_protocol_error: 0 + http.ingress_http.downstream_cx_rx_bytes_buffered: 0 + http.ingress_http.downstream_cx_rx_bytes_total: 250 + http.ingress_http.downstream_cx_ssl_active: 0 + http.ingress_http.downstream_cx_ssl_total: 0 + http.ingress_http.downstream_cx_total: 3 + http.ingress_http.downstream_cx_tx_bytes_buffered: 0 + http.ingress_http.downstream_cx_tx_bytes_total: 1117 + http.ingress_http.downstream_cx_upgrades_active: 0 + http.ingress_http.downstream_cx_upgrades_total: 0 + http.ingress_http.downstream_flow_control_paused_reading_total: 0 + http.ingress_http.downstream_flow_control_resumed_reading_total: 0 + http.ingress_http.downstream_rq_1xx: 0 + http.ingress_http.downstream_rq_2xx: 3 + http.ingress_http.downstream_rq_3xx: 0 + http.ingress_http.downstream_rq_4xx: 0 + http.ingress_http.downstream_rq_5xx: 0 + http.ingress_http.downstream_rq_active: 0 + http.ingress_http.downstream_rq_completed: 3 + http.ingress_http.downstream_rq_http1_total: 3 + http.ingress_http.downstream_rq_http2_total: 0 + http.ingress_http.downstream_rq_http3_total: 0 + http.ingress_http.downstream_rq_idle_timeout: 0 + http.ingress_http.downstream_rq_max_duration_reached: 0 + http.ingress_http.downstream_rq_non_relative_path: 0 + http.ingress_http.downstream_rq_overload_close: 0 + http.ingress_http.downstream_rq_response_before_rq_complete: 0 + http.ingress_http.downstream_rq_rx_reset: 0 + http.ingress_http.downstream_rq_timeout: 0 + http.ingress_http.downstream_rq_too_large: 0 + http.ingress_http.downstream_rq_total: 3 + http.ingress_http.downstream_rq_tx_reset: 0 + http.ingress_http.downstream_rq_ws_on_non_ws_route: 0 + http.ingress_http.no_cluster: 0 + http.ingress_http.no_route: 0 + http.ingress_http.passthrough_internal_redirect_bad_location: 0 + http.ingress_http.passthrough_internal_redirect_no_route: 0 + http.ingress_http.passthrough_internal_redirect_predicate: 0 + http.ingress_http.passthrough_internal_redirect_too_many_redirects: 0 + http.ingress_http.passthrough_internal_redirect_unsafe_scheme: 0 + http.ingress_http.rq_direct_response: 0 + http.ingress_http.rq_redirect: 0 + http.ingress_http.rq_reset_after_downstream_response_started: 0 + http.ingress_http.rq_total: 3 + http.ingress_http.rs_too_large: 0 + http.ingress_http.tracing.client_enabled: 0 + http.ingress_http.tracing.health_check: 0 + http.ingress_http.tracing.not_traceable: 0 + http.ingress_http.tracing.random_sampling: 0 + http.ingress_http.tracing.service_forced: 0 + 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) + 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 :ref:`format ` argument, for example to return ``json``: + +.. code-block:: console + + $ curl -s "http://localhost:19000/stats?filter=http.ingress_http.rq&format=json" | jq '.stats' + +.. code-block:: json + + [ + { + "value": 0, + "name": "http.ingress_http.rq_direct_response" + }, + { + "value": 0, + "name": "http.ingress_http.rq_redirect" + }, + { + "value": 0, + "name": "http.ingress_http.rq_reset_after_downstream_response_started" + }, + { + "value": 3, + "name": "http.ingress_http.rq_total" + } + ] diff --git a/docs/root/start/quick-start/configuration-dynamic-control-plane.rst b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst index 3ceb430abe366..914a057eafc06 100644 --- a/docs/root/start/quick-start/configuration-dynamic-control-plane.rst +++ b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst @@ -19,7 +19,7 @@ At a minimum, you will need to start Envoy configured with the following section - :ref:`dynamic_resources ` to tell Envoy which configurations should be updated dynamically - :ref:`static_resources ` to specify where Envoy should retrieve its configuration from. -You can also add an :ref:`admin ` section if you wish to monitor Envoy or +You can also add an :ref:`admin ` section if you wish to monitor Envoy or retrieve stats or configuration information. The following sections walk through the dynamic configuration provided in the @@ -72,26 +72,3 @@ The ``xds_cluster`` is configured to query a control plane at http://my-control- :lines: 17-35 :lineno-start: 17 :emphasize-lines: 3-17 - -.. _start_quick_start_dynamic_admin: - -``admin`` ---------- - -Configuring the :ref:`admin ` section is -the same as for :ref:`static configuration `. - -Enabling the :ref:`admin ` interface with -dynamic configuration, allows you to use the :ref:`config_dump ` -endpoint to see how Envoy is currently configured. - -.. literalinclude:: _include/envoy-dynamic-control-plane-demo.yaml - :language: yaml - :linenos: - :lines: 33-40 - :lineno-start: 33 - :emphasize-lines: 3-8 - -.. warning:: - - You may wish to restrict the network address the admin server listens to in your own deployment. diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index f6d55cf7a43b4..dc6c02100e1b3 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -19,7 +19,7 @@ For the given example you will also need two dynamic configuration files: - :ref:`lds.yaml ` for listeners. - :ref:`cds.yaml ` for clusters. -You can also add an :ref:`admin ` section if you wish to monitor Envoy or +You can also add an :ref:`admin ` section if you wish to monitor Envoy or retrieve stats or configuration information. The following sections walk through the dynamic configuration provided in the @@ -90,26 +90,3 @@ proxies over ``TLS`` to https://www.envoyproxy.io. :language: yaml :linenos: :emphasize-lines: 8, 14-15, 19-20 - -.. _start_quick_start_dynamic_fs_admin: - -``admin`` ---------- - -Configuring the :ref:`admin ` section is -the same as for :ref:`static configuration `. - -Enabling the :ref:`admin ` interface with -dynamic configuration, allows you to use the :ref:`config_dump ` -endpoint to see how Envoy is currently configured. - -.. literalinclude:: _include/envoy-dynamic-filesystem-demo.yaml - :language: yaml - :linenos: - :lines: 9-16 - :lineno-start: 9 - :emphasize-lines: 3-8 - -.. warning:: - - You may wish to restrict the network address the admin server listens to in your own deployment. diff --git a/docs/root/start/quick-start/configuration-static.rst b/docs/root/start/quick-start/configuration-static.rst index 74e539b529d0d..c9600c99bfd31 100644 --- a/docs/root/start/quick-start/configuration-static.rst +++ b/docs/root/start/quick-start/configuration-static.rst @@ -7,7 +7,7 @@ To start Envoy with static configuration, you will need to specify :ref:`listene and :ref:`clusters ` as :ref:`static_resources `. -You can also add an :ref:`admin ` section if you wish to monitor Envoy +You can also add an :ref:`admin ` section if you wish to monitor Envoy or retrieve stats. The following sections walk through the static configuration provided in the @@ -55,26 +55,5 @@ proxies over ``TLS`` to https://www.envoyproxy.io. .. literalinclude:: _include/envoy-demo.yaml :language: yaml :lineno-start: 27 - :lines: 27-50 + :lines: 27-48 :emphasize-lines: 3-22 - -.. _start_quick_start_static_admin: - -``admin`` ---------- - -The :ref:`admin message ` is required to enable and configure -the administration server. - -The ``address`` key specifies the listening :ref:`address ` -which in the demo configuration is ``0.0.0.0:9901``. - -.. literalinclude:: _include/envoy-demo.yaml - :language: yaml - :lineno-start: 48 - :lines: 48-55 - :emphasize-lines: 3-8 - -.. warning:: - - You may wish to restrict the network address the admin server listens to in your own deployment. diff --git a/docs/root/start/quick-start/index.rst b/docs/root/start/quick-start/index.rst index cc2078926cc75..e9daf8cf96efa 100644 --- a/docs/root/start/quick-start/index.rst +++ b/docs/root/start/quick-start/index.rst @@ -13,5 +13,6 @@ provides an introduction to the types of configuration Envoy can be used with. configuration-static configuration-dynamic-filesystem configuration-dynamic-control-plane + admin securing next-steps