docs: add admin endpoint gating guidance with allow_paths examples

api/envoy/config/bootstrap/v3/bootstrap.proto

@@ -469,6 +469,8 @@ message Admin {
   bool ignore_global_conn_limit = 6;
 
   // List of admin paths that are accessible. If not specified, all admin endpoints are accessible.
+  // Matchers are evaluated against the request path. For endpoints commonly queried with
+  // parameters (for example ``/stats?format=...``), prefer ``prefix`` matchers.
   //
   // When specified, only paths in this list will be accessible, all others will return ``HTTP 403 Forbidden``.
   //
@@ -477,7 +479,8 @@ message Admin {
   // .. code-block:: yaml
   //
   //   allow_paths:
-  //   - exact: /stats
+  //   - prefix: /stats
+  //   - prefix: /config_dump
   //   - exact: /ready
   //   - prefix: /healthcheck
   //

configs/admin-interface.yaml

@@ -0,0 +1,39 @@
+admin:
+  address:
+    socket_address:
+      protocol: TCP
+      address: 127.0.0.1
+      port_value: 9901
+  allow_paths:
+  - exact: /ready
+  - prefix: /stats
+  profile_path: /tmp/envoy.prof
+static_resources:
+  listeners:
+  - name: listener_0
+    address:
+      socket_address:
+        protocol: TCP
+        address: 127.0.0.1
+        port_value: 10000
+    filter_chains:
+    - filters:
+      - name: envoy.filters.network.tcp_proxy
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy
+          stat_prefix: local_tcp
+          cluster: local_service
+  clusters:
+  - name: local_service
+    connect_timeout: 1s
+    type: STATIC
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: local_service
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: 127.0.0.1
+                port_value: 8080

docs/root/operations/admin.rst

@@ -18,18 +18,17 @@ modify different aspects of the server:
   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:
-
-  .. code-block:: yaml
-
-    admin:
-      profile_path: /tmp/envoy.prof
-      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 <https://github.com/envoyproxy/envoy/issues/2763>`_ issue.
+  access to the administration listener via localhost. You can additionally restrict which admin
+  paths are reachable using
+  :ref:`allow_paths <envoy_v3_api_field_config.bootstrap.v3.Admin.allow_paths>`.
+  This can be accomplished with a configuration like the following:
+
+  .. literalinclude:: /_configs/repo/admin-interface.yaml
+    :language: yaml
+    :start-at: admin:
+    :end-before: static_resources:
+    :emphasize-lines: 7-9
+    :caption: :download:`admin-interface.yaml </_configs/repo/admin-interface.yaml>`
 
   All mutations must be sent as HTTP POST operations. When a mutation is requested via GET,
   the request has no effect, and an HTTP 400 (Invalid Request) response is returned.

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

@@ -27,18 +27,14 @@ The :ref:`admin message <envoy_v3_api_msg_config.bootstrap.v3.Admin>` is require
 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``.
+which in this example configuration is ``127.0.0.1:9901``.
 
-In this example, the logs are simply discarded.
-
-.. code-block:: yaml
-   :emphasize-lines: 4-5
-
-   admin:
-     address:
-       socket_address:
-         address: 0.0.0.0
-         port_value: 9901
+.. literalinclude:: /_configs/repo/admin-interface.yaml
+   :language: yaml
+   :start-at: admin:
+   :end-before: allow_paths:
+   :emphasize-lines: 5-6
+   :caption: :download:`admin-interface.yaml </_configs/repo/admin-interface.yaml>`
 
 .. warning::
 
@@ -50,6 +46,20 @@ In this example, the logs are simply discarded.
    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.
 
+You can also restrict which admin endpoints are exposed using
+:ref:`allow_paths <envoy_v3_api_field_config.bootstrap.v3.Admin.allow_paths>`.
+This is useful when the admin listener is used for limited purposes, such as a readiness probe.
+
+Use ``prefix`` matchers for endpoints that are commonly queried with parameters (for example
+``/stats?filter=...``).
+
+.. literalinclude:: /_configs/repo/admin-interface.yaml
+   :language: yaml
+   :start-at: admin:
+   :end-before: static_resources:
+   :emphasize-lines: 7-9
+   :caption: :download:`admin-interface.yaml </_configs/repo/admin-interface.yaml>`
+
 
 ``stat_prefix``
 ---------------