docs: Add quick-start admin page

.azure-pipelines/pipelines.yml

@@ -59,7 +59,10 @@ stages:
               GCP_SERVICE_ACCOUNT_KEY: $(GcpServiceAccountKey)
             displayName: "Generate docs"
 
-          - script: ci/run_envoy_docker.sh 'ci/upload_gcs_artifact.sh /source/generated/docs docs'
+          - script: |
+              SHORT_COMMIT_SHA=$(git log --pretty=%P -n 1 | cut -d' ' -f2 | head -c7)
+              export SHORT_COMMIT_SHA
+              ci/run_envoy_docker.sh 'ci/upload_gcs_artifact.sh /source/generated/docs docs'
             displayName: "Upload Docs to GCS"
             env:
               ENVOY_DOCKER_BUILD_DIR: $(Build.StagingDirectory)

ci/run_envoy_docker.sh

@@ -91,6 +91,7 @@ docker run --rm \
        -e BAZELISK_BASE_URL \
        -e ENVOY_BUILD_ARCH \
        -e SLACK_TOKEN \
+       -e SHORT_COMMIT_SHA \
        -e BUILD_URI\
        -e REPO_URI \
        "${ENVOY_BUILD_IMAGE}" \

ci/upload_gcs_artifact.sh

@@ -18,8 +18,13 @@ if [ ! -d "${SOURCE_DIRECTORY}" ]; then
   exit 1
 fi
 
-BRANCH=${SYSTEM_PULLREQUEST_PULLREQUESTNUMBER:-${BUILD_SOURCEBRANCHNAME}}
-GCS_LOCATION="${GCS_ARTIFACT_BUCKET}/${BRANCH}/${TARGET_SUFFIX}"
+if [ -n "${SHORT_COMMIT_SHA}" ]; then
+    UPLOAD_PATH="${SHORT_COMMIT_SHA}"
+else
+    UPLOAD_PATH="${SYSTEM_PULLREQUEST_PULLREQUESTNUMBER:-${BUILD_SOURCEBRANCHNAME}}"
+fi
+
+GCS_LOCATION="${GCS_ARTIFACT_BUCKET}/${UPLOAD_PATH}/${TARGET_SUFFIX}"
 
 echo "Uploading to gs://${GCS_LOCATION} ..."
 gsutil -mq rsync -dr "${SOURCE_DIRECTORY}" "gs://${GCS_LOCATION}"

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

docs/root/start/quick-start/admin.rst

@@ -0,0 +1,238 @@
+.. _start_quick_start_admin:
+
+Envoy admin interface
+=====================
+
+The optional admin interface provided by Envoy allows you to dump configuration and statistics, change the
+behaviour of the server, and tap traffic according to specific filter rules.
+
+The admin interface can be configured for static and dynamic setups.
+
+Enabling the :ref:`admin <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.admin>` interface with
+dynamic configuration can be particularly useful as it allows you to use the
+:ref:`config_dump <start_quick_start_admin_config_dump>` endpoint to see how Envoy is configured at
+a particular point in time.
+
+This guide provides configuration information, and some basic examples of using a couple of the admin
+endpoints.
+
+See the :ref:`admin docs <operations_admin_interface>` for information on all of the available endpoints.
+
+Some of the examples below make use of the `jq <https://stedolan.github.io/jq/>`_ tool to parse the output
+from the admin server.
+
+.. _start_quick_start_admin_config:
+
+``admin``
+---------
+
+The :ref:`admin message <envoy_v3_api_msg_config.bootstrap.v3.Admin>` is required to enable and configure
+the administration server.
+
+The ``address`` key specifies the listening :ref:`address <envoy_v3_api_file_envoy/config/core/v3/address.proto>`
+which in the demo configuration is ``0.0.0.0:9901``.
+
+You must set the ``access_log_path`` to specify where to send 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::
+
+   You may wish to restrict the network address the admin server listens to in your own deployment.
+
+
+``stats_prefix``
+----------------
+
+The Envoy ``HttpConnectionManager`` must be configured with ``stats_prefix``.
+
+This provides a key that can be filtered when querying the stats interface
+:ref:`as shown below <start_quick_start_admin_stats>`
+
+In the :download:`envoy-demo.yaml <_include/envoy-demo.yaml>` the listener is configured with the
+``stats_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 <operations_admin_interface_config_dump>` endpoint dumps Envoy's configuration
+in ``json`` format.
+
+The following command allows you to see the types of config 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 dump the ``socket_address`` of the first ``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
+     }
+   }
+
+See the reference section for :ref:`config_dump <operations_admin_interface_config_dump>` for further information
+on available parameters and responses.
+
+.. _start_quick_start_admin_stats:
+
+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:
+
+.. 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 ``filter`` ``regex`` argument:
+
+.. 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 ``format`` argument, for example to return ``json``:
+
+.. code-block:: console
+
+   $ curl -s "http://localhost:19000/stats?filter=http.ingress_http.rq&format=json" | jq '.'
+
+.. code-block:: json
+
+   {
+     "stats": [
+       {
+         "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"
+       }
+     ]
+   }

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 <start_quick_start_dynamic_dynamic_resources>` to tell Envoy which configurations should be updated dynamically
 - :ref:`static_resources <start_quick_start_dynamic_static_resources>` to specify where Envoy should retrieve its configuration from.
 
-You can also add an :ref:`admin <start_quick_start_dynamic_admin>` section if you wish to monitor Envoy or
+You can also add an :ref:`admin <start_quick_start_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 <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.admin>` section is
-the same as for :ref:`static configuration <start_quick_start_static_admin>`.
-
-Enabling the :ref:`admin <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.admin>` interface with
-dynamic configuration, allows you to use the :ref:`config_dump <operations_admin_interface_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.

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 <start_quick_start_dynamic_fs_dynamic_lds>` for listeners.
 - :ref:`cds.yaml <start_quick_start_dynamic_fs_dynamic_cds>` for clusters.
 
-You can also add an :ref:`admin <start_quick_start_dynamic_fs_admin>` section if you wish to monitor Envoy or
+You can also add an :ref:`admin <start_quick_start_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 <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.admin>` section is
-the same as for :ref:`static configuration <start_quick_start_static_admin>`.
-
-Enabling the :ref:`admin <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.admin>` interface with
-dynamic configuration, allows you to use the :ref:`config_dump <operations_admin_interface_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.

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 <start_quick_start_static_clusters>` as
 :ref:`static_resources <start_quick_start_static_static_resources>`.
 
-You can also add an :ref:`admin <start_quick_start_static_admin>` section if you wish to monitor Envoy
+You can also add an :ref:`admin <start_quick_start_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 <envoy_v3_api_msg_config.bootstrap.v3.Admin>` is required to enable and configure
-the administration server.
-
-The ``address`` key specifies the listening :ref:`address <envoy_v3_api_file_envoy/config/core/v3/address.proto>`
-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.