docs: Update quick-start

docs/root/start/_include/envoy-dynamic-demo.yaml

@@ -0,0 +1,56 @@
+node:
+  cluster: test-cluster
+  id: test-id
+
+dynamic_resources:
+  ads_config:
+    api_type: GRPC
+    transport_api_version: V3
+    grpc_services:
+    - envoy_grpc:
+        cluster_name: xds_cluster
+    set_node_on_first_message_only: false
+  cds_config:
+    resource_api_version: V3
+    ads: {}
+  lds_config:
+    resource_api_version: V3
+    ads: {}
+
+static_resources:
+  clusters:
+  - connect_timeout: 1s
+    type: strict_dns
+    load_assignment:
+      cluster_name: xds_cluster
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: go-control-plane
+                port_value: 18000
+    http2_protocol_options: {}
+    name: xds_cluster
+
+layered_runtime:
+  layers:
+    - name: runtime-0
+      rtds_layer:
+        rtds_config:
+          resource_api_version: V3
+          ads: {}
+        name: runtime-0
+    - name: runtime-1
+      rtds_layer:
+        rtds_config:
+          resource_api_version: V3
+          ads: {}
+        name: runtime-1
+
+admin:
+  access_log_path: /dev/null
+  address:
+    socket_address:
+      address: 0.0.0.0
+      port_value: 19000

docs/root/start/quick-start.rst

@@ -7,6 +7,8 @@ Quick start
 The following instructions walk through starting Envoy as a system daemon or using
 the Envoy Docker image.
 
+.. _start_quick_start_version:
+
 Check your Envoy version
 ------------------------
 
@@ -26,6 +28,7 @@ Once you have :ref:`installed Envoy <install>`, you can check the version inform
 
 	 $ docker run --rm envoyproxy/|envoy_docker_image| --version
 
+.. _start_quick_start_help:
 
 View the Envoy command line options
 -----------------------------------
@@ -47,6 +50,7 @@ flag:
 
 	 $ docker run --rm envoyproxy/|envoy_docker_image| --help
 
+.. _start_quick_start_config:
 
 Run Envoy with the demo configuration
 -------------------------------------
@@ -91,6 +95,7 @@ The Envoy admin endpoint should also be available at http://localhost:9901
 
    $ curl -v localhost:9901
 
+.. _start_quick_start_override:
 
 Override the default configuration by merging a config file
 -----------------------------------------------------------
@@ -136,31 +141,39 @@ The Envoy admin endpoint should also be available at http://localhost:9901
 
    $ curl -v localhost:9901
 
+.. _start_quick_start_static:
 
 Static configuration
 --------------------
 
-To start Envoy with static configuration, you will need to specify ``listeners`` and ``clusters``
-as ``static_resources``.
+To start Envoy with static configuration, you will need to specify :ref:`listeners <start_quick_start_static_listeners>`
+and :ref:`clusters <start_quick_start_static_clusters>` as
+:ref:`static_resources <start_quick_start_static_static_resources>`.
 
-You can also add an ``admin`` section if you wish to monitor Envoy or retrieve stats.
+You can also add an :ref:`admin <start_quick_start_static_admin>` section if you wish to monitor Envoy
+or retrieve stats.
 
-The following sections walk through the static configuration provided in the :download:`demo configuration file <_include/envoy-demo.yaml>`.
+The following sections walk through the static configuration provided in the
+:download:`demo configuration file <_include/envoy-demo.yaml>`.
 
-Configuration: static_resources
-*******************************
+.. _start_quick_start_static_static_resources:
+
+Static configuration: ``static_resources``
+******************************************
 
-The :ref:`static_resources <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.static_resources>` contains everything that is configured statically when Envoy starts,
-as opposed to the means of configuring resources dynamically when Envoy is running.
+The :ref:`static_resources <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.static_resources>` contains
+everything that is configured statically when Envoy starts, as opposed to dynamically at runtime.
 
 .. literalinclude:: _include/envoy-demo.yaml
     :language: yaml
     :linenos:
     :lines: 1-3
     :emphasize-lines: 1
 
-Configuration: listeners
-************************
+.. _start_quick_start_static_listeners:
+
+Static configuration: ``listeners``
+***********************************
 
 The specification of the :ref:`listeners <envoy_v3_api_file_envoy/config/listener/v3/listener.proto>`.
 
@@ -170,9 +183,10 @@ The specification of the :ref:`listeners <envoy_v3_api_file_envoy/config/listene
     :lines: 1-25
     :emphasize-lines: 3-23
 
+.. _start_quick_start_static_clusters:
 
-Configuration: clusters
-***********************
+Static configuration: ``clusters``
+**********************************
 
 The specification of the :ref:`clusters <envoy_v3_api_file_envoy/service/cluster/v3/cds.proto>`.
 
@@ -182,8 +196,10 @@ The specification of the :ref:`clusters <envoy_v3_api_file_envoy/service/cluster
     :lines: 22-47
     :emphasize-lines: 4-24
 
-Configuration: admin
-********************
+.. _start_quick_start_static_admin:
+
+Static configuration: ``admin``
+*******************************
 
 The :ref:`admin message <envoy_v3_api_msg_config.bootstrap.v3.Admin>` is required to configure
 the administration server.
@@ -201,12 +217,111 @@ which in the demo configuration is ``0.0.0.0:9901``.
 
    You may wish to restrict the network address the admin server listens to in your own deployment.
 
+.. _start_quick_start_dynamic:
 
 Dynamic configuration
 ---------------------
 
-See the :ref:`configuration overview <config_overview>` for further information on configuring Envoy with static and dynamic configuration.
+Setting up Envoy with dynamic configuration is slightly more complex as you must also set up a control plane
+to provide Envoy with its configuration.
+
+There are a number of control planes compatible with Envoy's API such as `Gloo <https://docs.solo.io/gloo/latest/>`_
+or `Istiod <https://istio.io/latest/docs/ops/deployment/architecture/#istiod>`_.
+
+You may also wish to explore implementing your own control plane, in which case the
+`Go Control Plane <https://github.com/envoyproxy/go-control-plane>`_ provides a reference implementation
+that is a good place to start.
+
+At a minimum, you will need to start Envoy configured with the following sections:
+
+- :ref:`node <start_quick_start_dynamic_node>` information, to uniquely identify the proxy node.
+- :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.
+- :ref:`layered_runtime <start_quick_start_dynamic_layered_runtime>` to persist dynamically-provided configurations.
+
+You can also add an :ref:`admin <start_quick_start_dynamic_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
+:download:`demo dynamic configuration file <_include/envoy-dynamic-demo.yaml>`.
 
+.. _start_quick_start_dynamic_node:
+
+Dynamic configuration: ``node``
+*******************************
+
+The :ref:`node <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.node>` should specify...
+
+.. literalinclude:: _include/envoy-dynamic-demo.yaml
+    :language: yaml
+    :linenos:
+    :lines: 1-5
+    :emphasize-lines: 1-3
+
+.. _start_quick_start_dynamic_dynamic_resources:
+
+Dynamic configuration: ``dynamic_resources``
+********************************************
+
+The :ref:`dynamic_resources <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.dynamic_resources>` should specify...
+
+.. literalinclude:: _include/envoy-dynamic-demo.yaml
+    :language: yaml
+    :linenos:
+    :lines: 3-20
+    :lineno-start: 3
+    :emphasize-lines: 3-16
+
+.. _start_quick_start_dynamic_static_resources:
+
+Dynamic configuration: ``static_resources``
+*******************************************
+
+The :ref:`static_resources <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.static_resources>` should specify...
+
+.. literalinclude:: _include/envoy-dynamic-demo.yaml
+    :language: yaml
+    :linenos:
+    :lines: 18-36
+    :lineno-start: 18
+    :emphasize-lines: 3-17
+
+.. _start_quick_start_dynamic_layered_runtime:
+
+Dynamic configuration: ``layered_runtime``
+******************************************
+
+The :ref:`layered_runtime <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.layered_runtime>` should specify...
+
+.. literalinclude:: _include/envoy-dynamic-demo.yaml
+    :language: yaml
+    :linenos:
+    :lines: 34-51
+    :lineno-start: 34
+    :emphasize-lines: 3-16
+
+.. _start_quick_start_dynamic_admin:
+
+Dynamic configuration: ``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 see how Envoy is currently configured by using the
+:ref:`config_dump <operations_admin_interface_config_dump>` endpoint.
+
+.. literalinclude:: _include/envoy-dynamic-demo.yaml
+    :language: yaml
+    :linenos:
+    :lines: 51-56
+    :lineno-start: 51
+    :emphasize-lines: 1-6
+
+.. warning::
+
+   You may wish to restrict the network address the admin server listens to in your own deployment.
 
 Next steps
 ----------