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,39 @@
+.. _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.
+
+``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``.
+
+.. code-block:: yaml
+
+   admin:
+     access_log_path: /dev/null
+     address:
+       socket_address:
+         address: 0.0.0.0
+	 port_value: 19000
+
+.. warning::
+
+   You may wish to restrict the network address the admin server listens to in your own deployment.
+
+
+Admin endpoints: ``config_dump``
+--------------------------------
+
+
+Admin endpoints: ``stats``
+--------------------------

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.

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

@@ -13,4 +13,5 @@ provides an introduction to the types of configuration Envoy can be used with.
     configuration-static
     configuration-dynamic-filesystem
     configuration-dynamic-control-plane
+    admin
     next-steps