From 5e346af6a66ed7d4be280535fca3efc9c7024b7d Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Wed, 28 Oct 2020 08:24:11 +0000 Subject: [PATCH 01/24] docs: Further updates to quick-start Signed-off-by: Ryan Northey --- docs/BUILD | 1 + docs/redirects.txt | 2 + docs/root/start/quick-start.rst | 240 ------------------ .../_include/envoy-demo.yaml | 0 .../_include/envoy-dynamic-cds-demo.yaml | 16 ++ .../envoy-dynamic-control-plane-demo.yaml | 49 ++++ .../envoy-dynamic-filesystem-demo.yaml | 16 ++ .../_include/envoy-dynamic-lds-demo.yaml | 28 ++ .../dynamic-configuration-control-plane.rst | 114 +++++++++ .../dynamic-configuration-filesystem.rst | 49 ++++ docs/root/start/quick-start/index.rst | 15 ++ docs/root/start/quick-start/next-steps.rst | 9 + docs/root/start/quick-start/run-envoy.rst | 160 ++++++++++++ .../quick-start/static-configuration.rst | 81 ++++++ docs/root/start/start.rst | 2 +- 15 files changed, 541 insertions(+), 241 deletions(-) delete mode 100644 docs/root/start/quick-start.rst rename docs/root/start/{ => quick-start}/_include/envoy-demo.yaml (100%) create mode 100644 docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml create mode 100644 docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml create mode 100644 docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml create mode 100644 docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml create mode 100644 docs/root/start/quick-start/dynamic-configuration-control-plane.rst create mode 100644 docs/root/start/quick-start/dynamic-configuration-filesystem.rst create mode 100644 docs/root/start/quick-start/index.rst create mode 100644 docs/root/start/quick-start/next-steps.rst create mode 100644 docs/root/start/quick-start/run-envoy.rst create mode 100644 docs/root/start/quick-start/static-configuration.rst diff --git a/docs/BUILD b/docs/BUILD index aad5c89f0b653..65323e28015b5 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -17,6 +17,7 @@ filegroup( "root/**/*.pb", ], exclude = [ + "root/**/envoy-dynamic*.yaml", # TODO(phlax/windows-dev): figure out how to get this working on windows # "Error: unable to read file: /etc/ssl/certs/ca-certificates.crt" "root/configuration/http/http_filters/_include/dns-cache-circuit-breaker.yaml", diff --git a/docs/redirects.txt b/docs/redirects.txt index c4d2cb39faac1..e646e88d507a1 100644 --- a/docs/redirects.txt +++ b/docs/redirects.txt @@ -17,3 +17,5 @@ start/install/tools/tools.rst operations/tools/tools.rst start/install/tools/route_table_check_tool.rst operations/tools/route_table_check_tool.rst start/install/tools/schema_validator_check_tool.rst operations/tools/schema_validator_check_tool.rst start/install/tools/config_load_check_tool.rst operations/tools/config_load_check_tool.rst + +start/quick-start.rst start/quick-start/index.rst diff --git a/docs/root/start/quick-start.rst b/docs/root/start/quick-start.rst deleted file mode 100644 index 319832c71e910..0000000000000 --- a/docs/root/start/quick-start.rst +++ /dev/null @@ -1,240 +0,0 @@ -.. _start_quick_start: - - -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 ------------------------- - -Once you have :ref:`installed Envoy `, you can check the version information as follows: - -.. tabs:: - - .. tab:: System - - .. code-block:: console - - $ envoy --version - - .. tab:: Docker - - .. substitution-code-block:: console - - $ docker run --rm envoyproxy/|envoy_docker_image| --version - -.. _start_quick_start_help: - -View the Envoy command line options ------------------------------------ - -You can view the Envoy :ref:`command line options ` with the ``--help`` -flag: - -.. tabs:: - - .. tab:: System - - .. code-block:: console - - $ envoy --help - - .. tab:: Docker - - .. substitution-code-block:: console - - $ docker run --rm envoyproxy/|envoy_docker_image| --help - -.. _start_quick_start_config: - -Run Envoy with the demo configuration -------------------------------------- - -The ``-c`` or ``--config-path`` flag tells Envoy the path to its initial configuration. - -.. tabs:: - - .. tab:: System - - To start Envoy as a system daemon :download:`download the demo configuration <_include/envoy-demo.yaml>`, and start - as follows: - - .. code-block:: console - - $ envoy -c envoy-demo.yaml - - .. tab:: Docker - - You can start the Envoy Docker image without specifying a configuration file, and - it will use the demo config by default. - - .. substitution-code-block:: console - - $ docker run --rm -d -p 9901:9901 -p 10000:10000 envoyproxy/|envoy_docker_image| - - To specify a custom configuration you can mount the config into the container, and specify the path with ``-c``. - - Assuming you have a custom configuration in the current directory named ``envoy-custom.yaml``: - - .. substitution-code-block:: console - - $ docker run --rm -d -v $(pwd)/envoy-custom.yaml:/envoy-custom.yaml -p 9901:9901 -p 10000:10000 envoyproxy/|envoy_docker_image| -c /envoy-custom.yaml - -Check Envoy is proxying on http://localhost:10000 - -.. code-block:: console - - $ curl -v localhost:10000 - -The Envoy admin endpoint should also be available at http://localhost:9901 - -.. code-block:: console - - $ curl -v localhost:9901 - -.. _start_quick_start_override: - -Override the default configuration by merging a config file ------------------------------------------------------------ - -You can provide a configuration override file using ``--config-yaml`` which will merge with the main -configuration. - -Save the following snippet to ``envoy-override.yaml``: - -.. code-block:: yaml - - listeners: - - name: listener_0 - address: - socket_address: - port_value: 20000 - -Next, start the Envoy server using the override configuration. - -.. tabs:: - - .. tab:: System - - .. code-block:: console - - $ envoy -c envoy-demo.yaml --config-yaml envoy-override.yaml - - .. tab:: Docker - - .. substitution-code-block:: console - - $ docker run --rm -d -v $(pwd)/envoy-override.yaml:/envoy-override.yaml -p 20000:20000 envoyproxy/|envoy_docker_image| --config-yaml /envoy-override.yaml - -Envoy should now be proxying on http://localhost:20000 - -.. code-block:: console - - $ curl -v localhost:20000 - -The Envoy admin endpoint should also be available at http://localhost:9901 - -.. code-block:: console - - $ curl -v localhost:9901 - -.. _start_quick_start_static: - -Static configuration --------------------- - -To start Envoy with static configuration, you will need to specify :ref:`listeners ` -and :ref:`clusters ` as -:ref:`static_resources `. - -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 -:download:`demo configuration file <_include/envoy-demo.yaml>` used as the default in the Envoy Docker container. - -.. _start_quick_start_static_static_resources: - -Static configuration: ``static_resources`` -****************************************** - -The :ref:`static_resources ` contain -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 - -.. _start_quick_start_static_listeners: - -Static configuration: ``listeners`` -*********************************** - -The example configures a :ref:`listener ` -on port ``10000``. - -All paths are matched and routed to the ``service_envoyproxy_io`` -:ref:`cluster `. - -.. literalinclude:: _include/envoy-demo.yaml - :language: yaml - :linenos: - :lines: 1-29 - :emphasize-lines: 3-27 - -.. _start_quick_start_static_clusters: - -Static configuration: ``clusters`` -********************************** - -The ``service_envoyproxy_io`` :ref:`cluster ` -proxies over ``TLS`` to https://www.envoyproxy.io. - -.. literalinclude:: _include/envoy-demo.yaml - :language: yaml - :lineno-start: 27 - :lines: 27-50 - :emphasize-lines: 3-22 - -.. _start_quick_start_static_admin: - -Static configuration: ``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. - -.. _start_quick_start_dynamic: - -Dynamic configuration ---------------------- - -See the :ref:`configuration overview ` for further information on configuring Envoy with static and dynamic configuration. - -Next steps ----------- - -- Learn more about :ref:`using the Envoy Docker image ` -- Try out demo configurations in the :ref:`sandboxes ` -- Check out the :ref:`configuration generator ` and other - :ref:`Envoy tools ` diff --git a/docs/root/start/_include/envoy-demo.yaml b/docs/root/start/quick-start/_include/envoy-demo.yaml similarity index 100% rename from docs/root/start/_include/envoy-demo.yaml rename to docs/root/start/quick-start/_include/envoy-demo.yaml diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml new file mode 100644 index 0000000000000..738ed898c6411 --- /dev/null +++ b/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml @@ -0,0 +1,16 @@ +version_info: "1" +resources: +- "@type": type.googleapis.com/envoy.config.cluster.v3.Cluster + name: example_proxy_cluster + connect_timeout: 1s + type: strict_dns + http2_protocol_options: {} + load_assignment: + cluster_name: example_proxy_cluster + endpoints: + - lb_endpoints: + - endpoint: + address: + socket_address: + address: service1 + port_value: 8080 diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml new file mode 100644 index 0000000000000..2b0c443e6a11d --- /dev/null +++ b/docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml @@ -0,0 +1,49 @@ +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 + cds_config: + resource_api_version: V3 + ads: {} + lds_config: + resource_api_version: V3 + ads: {} + +static_resources: + clusters: + - connect_timeout: 1s + type: strict_dns + http2_protocol_options: {} + name: xds_cluster + load_assignment: + cluster_name: xds_cluster + endpoints: + - lb_endpoints: + - endpoint: + address: + socket_address: + address: my-control-plane + port_value: 18000 + +layered_runtime: + layers: + - name: runtime-0 + rtds_layer: + name: runtime-0 + rtds_config: + resource_api_version: V3 + ads: {} + +admin: + access_log_path: /dev/null + address: + socket_address: + address: 0.0.0.0 + port_value: 19000 diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml new file mode 100644 index 0000000000000..27587e0dbca40 --- /dev/null +++ b/docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml @@ -0,0 +1,16 @@ +node: + id: id_1 + cluster: test + +dynamic_resources: + cds_config: + path: /var/lib/envoy/cds.yaml + lds_config: + path: /var/lib/envoy/lds.yaml + +admin: + access_log_path: "/dev/null" + address: + socket_address: + address: 0.0.0.0 + port_value: 19000 diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml new file mode 100644 index 0000000000000..7893b6db20579 --- /dev/null +++ b/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml @@ -0,0 +1,28 @@ +version_info: "1" +resources: +- "@type": type.googleapis.com/envoy.config.listener.v3.Listener + name: listener_0 + address: + socket_address: + address: 0.0.0.0 + port_value: 10000 + filter_chains: + - filters: + name: envoy.http_connection_manager + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager + stat_prefix: ingress_http + codec_type: AUTO + route_config: + name: local_route + virtual_hosts: + - name: local_service + domains: + - "*" + routes: + - match: + prefix: "/" + route: + cluster: example_proxy_cluster + http_filters: + - name: envoy.router diff --git a/docs/root/start/quick-start/dynamic-configuration-control-plane.rst b/docs/root/start/quick-start/dynamic-configuration-control-plane.rst new file mode 100644 index 0000000000000..aa7dc67fd3ae4 --- /dev/null +++ b/docs/root/start/quick-start/dynamic-configuration-control-plane.rst @@ -0,0 +1,114 @@ +.. _start_quick_start_dynamic_control_plane: + +Dynamic configuration (control plane) +===================================== + +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 `_ +or `Istiod `_. + +You may also wish to explore implementing your own control plane, in which case the +`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 ` to uniquely identify the proxy node. +- :ref:`dynamic_resources ` to tell Envoy which configurations should be updated dynamically +- :ref:`static_resources ` to specify where Envoy should retrieve its configuration from. +- :ref:`layered_runtime ` to persist dynamically-provided configurations. + +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 +:download:`demo dynamic configuration file <_include/envoy-dynamic-control-plane-demo.yaml>`. + +.. _start_quick_start_dynamic_node: + +``node`` +-------- + +The :ref:`node ` should specify ``cluster`` and ``id``. + +.. literalinclude:: _include/envoy-dynamic-control-plane-demo.yaml + :language: yaml + :linenos: + :lines: 1-5 + :emphasize-lines: 1-3 + +.. _start_quick_start_dynamic_dynamic_resources: + +``dynamic_resources`` +--------------------- + +The :ref:`dynamic_resources ` specify +the configuration to load dynamically, and the :ref:`cluster ` +to connect to for dynamic configuration updates. + +In this example, the configuration is provided by the ``xds_cluster`` configured below. + +.. literalinclude:: _include/envoy-dynamic-control-plane-demo.yaml + :language: yaml + :linenos: + :lines: 3-19 + :lineno-start: 3 + :emphasize-lines: 3-15 + +.. _start_quick_start_dynamic_static_resources: + +``static_resources`` +-------------------- + +Here we specify the :ref:`static_resources ` +to retrieve dynamic configuration from. + +The ``xds_cluster`` is configured to query a control plane at http://my-control-plane:18000 . + +.. literalinclude:: _include/envoy-dynamic-control-plane-demo.yaml + :language: yaml + :linenos: + :lines: 17-35 + :lineno-start: 17 + :emphasize-lines: 3-17 + +.. _start_quick_start_dynamic_layered_runtime: + +``layered_runtime`` +------------------- + +A :ref:`layered_runtime ` is +required with an :ref:`rtds_layer ` +to persist configuration provided by the control plane. + +.. literalinclude:: _include/envoy-dynamic-control-plane-demo.yaml + :language: yaml + :linenos: + :lines: 33-44 + :lineno-start: 33 + :emphasize-lines: 3-10 + +.. _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: 42-49 + :lineno-start: 42 + :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/dynamic-configuration-filesystem.rst b/docs/root/start/quick-start/dynamic-configuration-filesystem.rst new file mode 100644 index 0000000000000..7bf1804f5646c --- /dev/null +++ b/docs/root/start/quick-start/dynamic-configuration-filesystem.rst @@ -0,0 +1,49 @@ +.. _start_quick_start_dynamic_filesystem: + +Dynamic configuration (filesystem) +================================== + +``node`` +-------- + +The :ref:`node ` should specify ``cluster`` and ``id``. + +.. literalinclude:: _include/envoy-dynamic-filesystem-demo.yaml + :language: yaml + :linenos: + :lines: 1-5 + :emphasize-lines: 1-3 + +``dynamic_resources`` +--------------------- + +.. literalinclude:: _include/envoy-dynamic-filesystem-demo.yaml + :language: yaml + :linenos: + :lines: 3-11 + :lineno-start: 3 + :emphasize-lines: 3-7 + +``admin`` +--------- + +.. literalinclude:: _include/envoy-dynamic-filesystem-demo.yaml + :language: yaml + :linenos: + :lines: 9-16 + :lineno-start: 9 + :emphasize-lines: 3-8 + +``resources`` - Listeners Discovery Service (LDS) +------------------------------------------------- + +.. literalinclude:: _include/envoy-dynamic-lds-demo.yaml + :language: yaml + :linenos: + +``resources`` - Clusters Discovery Service (CDS) +------------------------------------------------ + +.. literalinclude:: _include/envoy-dynamic-cds-demo.yaml + :language: yaml + :linenos: diff --git a/docs/root/start/quick-start/index.rst b/docs/root/start/quick-start/index.rst new file mode 100644 index 0000000000000..849e813bb8c11 --- /dev/null +++ b/docs/root/start/quick-start/index.rst @@ -0,0 +1,15 @@ +.. _start_quick_start: + +Quick start +=========== + +intro message + +.. toctree:: + :maxdepth: 3 + + run-envoy + static-configuration + dynamic-configuration-filesystem + dynamic-configuration-control-plane + next-steps diff --git a/docs/root/start/quick-start/next-steps.rst b/docs/root/start/quick-start/next-steps.rst new file mode 100644 index 0000000000000..e6e9b4afb1a29 --- /dev/null +++ b/docs/root/start/quick-start/next-steps.rst @@ -0,0 +1,9 @@ +.. _start_quick_start_next_steps: + +Next steps +========== + +- Learn more about :ref:`using the Envoy Docker image ` +- Try out demo configurations in the :ref:`sandboxes ` +- Check out the :ref:`configuration generator ` and other + :ref:`Envoy tools ` diff --git a/docs/root/start/quick-start/run-envoy.rst b/docs/root/start/quick-start/run-envoy.rst new file mode 100644 index 0000000000000..b3188c395522c --- /dev/null +++ b/docs/root/start/quick-start/run-envoy.rst @@ -0,0 +1,160 @@ +.. _start_quick_start_run_envoy: + + +Run Envoy +========= + +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 +------------------------ + +Once you have :ref:`installed Envoy `, you can check the version information as follows: + +.. tabs:: + + .. tab:: System + + .. code-block:: console + + $ envoy --version + + .. tab:: Docker + + .. substitution-code-block:: console + + $ docker run --rm \ + envoyproxy/|envoy_docker_image| \ + --version + +.. _start_quick_start_help: + +View the Envoy command line options +----------------------------------- + +You can view the Envoy :ref:`command line options ` with the ``--help`` +flag: + +.. tabs:: + + .. tab:: System + + .. code-block:: console + + $ envoy --help + + .. tab:: Docker + + .. substitution-code-block:: console + + $ docker run --rm \ + envoyproxy/|envoy_docker_image| \ + --help + +.. _start_quick_start_config: + +Run Envoy with the demo configuration +------------------------------------- + +The ``-c`` or ``--config-path`` flag tells Envoy the path to its initial configuration. + +.. tabs:: + + .. tab:: System + + To start Envoy as a system daemon :download:`download the demo configuration <_include/envoy-demo.yaml>`, and start + as follows: + + .. code-block:: console + + $ envoy -c envoy-demo.yaml + + .. tab:: Docker + + You can start the Envoy Docker image without specifying a configuration file, and + it will use the demo config by default. + + .. substitution-code-block:: console + + $ docker run --rm -d \ + -p 9901:9901 \ + -p 10000:10000 \ + envoyproxy/|envoy_docker_image| + + To specify a custom configuration you can mount the config into the container, and specify the path with ``-c``. + + Assuming you have a custom configuration in the current directory named ``envoy-custom.yaml``: + + .. substitution-code-block:: console + + $ docker run --rm -d \ + -v $(pwd)/envoy-custom.yaml:/envoy-custom.yaml \ + -p 9901:9901 \ + -p 10000:10000 \ + envoyproxy/|envoy_docker_image| \ + -c /envoy-custom.yaml + +Check Envoy is proxying on http://localhost:10000 + +.. code-block:: console + + $ curl -v localhost:10000 + +The Envoy admin endpoint should also be available at http://localhost:9901 + +.. code-block:: console + + $ curl -v localhost:9901 + +.. _start_quick_start_override: + +Override the default configuration by merging a config file +----------------------------------------------------------- + +You can provide a configuration override file using ``--config-yaml`` which will merge with the main +configuration. + +Save the following snippet to ``envoy-override.yaml``: + +.. code-block:: yaml + + listeners: + - name: listener_0 + address: + socket_address: + port_value: 20000 + +Next, start the Envoy server using the override configuration. + +.. tabs:: + + .. tab:: System + + .. code-block:: console + + $ envoy -c envoy-demo.yaml --config-yaml envoy-override.yaml + + .. tab:: Docker + + .. substitution-code-block:: console + + $ docker run --rm -d \ + -v $(pwd)/envoy-override.yaml:/envoy-override.yaml \ + -p 20000:20000 \ + envoyproxy/|envoy_docker_image| \ + --config-yaml /envoy-override.yaml + +Envoy should now be proxying on http://localhost:20000 + +.. code-block:: console + + $ curl -v localhost:20000 + +The Envoy admin endpoint should also be available at http://localhost:9901 + +.. code-block:: console + + $ curl -v localhost:9901 diff --git a/docs/root/start/quick-start/static-configuration.rst b/docs/root/start/quick-start/static-configuration.rst new file mode 100644 index 0000000000000..116fe440f44bd --- /dev/null +++ b/docs/root/start/quick-start/static-configuration.rst @@ -0,0 +1,81 @@ + +.. _start_quick_start_static: + +Static configuration +==================== + +To start Envoy with static configuration, you will need to specify :ref:`listeners ` +and :ref:`clusters ` as +:ref:`static_resources `. + +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 +:download:`demo configuration file <_include/envoy-demo.yaml>` used as the default in the Envoy Docker container. + +.. _start_quick_start_static_static_resources: + +``static_resources`` +-------------------- + +The :ref:`static_resources ` contain +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 + +.. _start_quick_start_static_listeners: + +``listeners`` +------------- + +The example configures a :ref:`listener ` +on port ``10000``. + +All paths are matched and routed to the ``service_envoyproxy_io`` +:ref:`cluster `. + +.. literalinclude:: _include/envoy-demo.yaml + :language: yaml + :linenos: + :lines: 1-29 + :emphasize-lines: 3-27 + +.. _start_quick_start_static_clusters: + +``clusters`` +------------ + +The ``service_envoyproxy_io`` :ref:`cluster ` +proxies over ``TLS`` to https://www.envoyproxy.io. + +.. literalinclude:: _include/envoy-demo.yaml + :language: yaml + :lineno-start: 27 + :lines: 27-50 + :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/start.rst b/docs/root/start/start.rst index 27c3b31c1ad85..2747baa3e3345 100644 --- a/docs/root/start/start.rst +++ b/docs/root/start/start.rst @@ -16,7 +16,7 @@ feature of the API, which is most useful for simple requirements. For more compl :maxdepth: 3 install - quick-start + quick-start/index docker building From 455784dc6d274899011957ed7a38f370ad0351cd Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Wed, 28 Oct 2020 14:41:17 +0000 Subject: [PATCH 02/24] docs/ Signed-off-by: Ryan Northey --- .../dynamic-configuration-filesystem.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/root/start/quick-start/dynamic-configuration-filesystem.rst b/docs/root/start/quick-start/dynamic-configuration-filesystem.rst index 7bf1804f5646c..5a5d8ea07b2f6 100644 --- a/docs/root/start/quick-start/dynamic-configuration-filesystem.rst +++ b/docs/root/start/quick-start/dynamic-configuration-filesystem.rst @@ -24,16 +24,6 @@ The :ref:`node ` should s :lineno-start: 3 :emphasize-lines: 3-7 -``admin`` ---------- - -.. literalinclude:: _include/envoy-dynamic-filesystem-demo.yaml - :language: yaml - :linenos: - :lines: 9-16 - :lineno-start: 9 - :emphasize-lines: 3-8 - ``resources`` - Listeners Discovery Service (LDS) ------------------------------------------------- @@ -47,3 +37,13 @@ The :ref:`node ` should s .. literalinclude:: _include/envoy-dynamic-cds-demo.yaml :language: yaml :linenos: + +``admin`` +--------- + +.. literalinclude:: _include/envoy-dynamic-filesystem-demo.yaml + :language: yaml + :linenos: + :lines: 9-16 + :lineno-start: 9 + :emphasize-lines: 3-8 From b35000a885068cd44dda350a2eafdadf751c90fa Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Wed, 28 Oct 2020 14:56:06 +0000 Subject: [PATCH 03/24] docs/ Signed-off-by: Ryan Northey --- .../start/quick-start/_include/envoy-dynamic-cds-demo.yaml | 1 + .../start/quick-start/_include/envoy-dynamic-lds-demo.yaml | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml index 738ed898c6411..5b58accbc71d6 100644 --- a/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml +++ b/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml @@ -1,4 +1,5 @@ version_info: "1" + resources: - "@type": type.googleapis.com/envoy.config.cluster.v3.Cluster name: example_proxy_cluster diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml index 7893b6db20579..7febaca551362 100644 --- a/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml +++ b/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml @@ -1,4 +1,5 @@ version_info: "1" + resources: - "@type": type.googleapis.com/envoy.config.listener.v3.Listener name: listener_0 @@ -12,7 +13,8 @@ resources: typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager stat_prefix: ingress_http - codec_type: AUTO + http_filters: + - name: envoy.router route_config: name: local_route virtual_hosts: @@ -24,5 +26,3 @@ resources: prefix: "/" route: cluster: example_proxy_cluster - http_filters: - - name: envoy.router From 57c8581de738f22cfa5f113184522ec14ecf44a3 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Wed, 28 Oct 2020 15:18:21 +0000 Subject: [PATCH 04/24] docs/ Signed-off-by: Ryan Northey --- ...ol-plane.rst => configuration-dynamic-control-plane.rst} | 4 ++-- ...-filesystem.rst => configuration-dynamic-filesystem.rst} | 4 ++-- .../{static-configuration.rst => configuration-static.rst} | 4 ++-- docs/root/start/quick-start/index.rst | 6 +++--- 4 files changed, 9 insertions(+), 9 deletions(-) rename docs/root/start/quick-start/{dynamic-configuration-control-plane.rst => configuration-dynamic-control-plane.rst} (98%) rename docs/root/start/quick-start/{dynamic-configuration-filesystem.rst => configuration-dynamic-filesystem.rst} (93%) rename docs/root/start/quick-start/{static-configuration.rst => configuration-static.rst} (98%) diff --git a/docs/root/start/quick-start/dynamic-configuration-control-plane.rst b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst similarity index 98% rename from docs/root/start/quick-start/dynamic-configuration-control-plane.rst rename to docs/root/start/quick-start/configuration-dynamic-control-plane.rst index aa7dc67fd3ae4..985cce2f5ccfd 100644 --- a/docs/root/start/quick-start/dynamic-configuration-control-plane.rst +++ b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst @@ -1,7 +1,7 @@ .. _start_quick_start_dynamic_control_plane: -Dynamic configuration (control plane) -===================================== +Configuration: Dynamic from control plane +========================================= 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. diff --git a/docs/root/start/quick-start/dynamic-configuration-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst similarity index 93% rename from docs/root/start/quick-start/dynamic-configuration-filesystem.rst rename to docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 5a5d8ea07b2f6..a1c17359fcc6b 100644 --- a/docs/root/start/quick-start/dynamic-configuration-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -1,7 +1,7 @@ .. _start_quick_start_dynamic_filesystem: -Dynamic configuration (filesystem) -================================== +Configuration: Dynamic from filesystem +====================================== ``node`` -------- diff --git a/docs/root/start/quick-start/static-configuration.rst b/docs/root/start/quick-start/configuration-static.rst similarity index 98% rename from docs/root/start/quick-start/static-configuration.rst rename to docs/root/start/quick-start/configuration-static.rst index 116fe440f44bd..397fa5b40c794 100644 --- a/docs/root/start/quick-start/static-configuration.rst +++ b/docs/root/start/quick-start/configuration-static.rst @@ -1,8 +1,8 @@ .. _start_quick_start_static: -Static configuration -==================== +Configuration: Static +===================== To start Envoy with static configuration, you will need to specify :ref:`listeners ` and :ref:`clusters ` as diff --git a/docs/root/start/quick-start/index.rst b/docs/root/start/quick-start/index.rst index 849e813bb8c11..2ab91d96155d9 100644 --- a/docs/root/start/quick-start/index.rst +++ b/docs/root/start/quick-start/index.rst @@ -9,7 +9,7 @@ intro message :maxdepth: 3 run-envoy - static-configuration - dynamic-configuration-filesystem - dynamic-configuration-control-plane + configuration-static + configuration-dynamic-filesystem + configuration-dynamic-control-plane next-steps From 2a60fdd393c71abba83dc8e011da58e712ba840a Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Wed, 28 Oct 2020 15:21:20 +0000 Subject: [PATCH 05/24] docs/ Signed-off-by: Ryan Northey --- .../root/start/quick-start/configuration-dynamic-filesystem.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index a1c17359fcc6b..768abc0f7251b 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -30,6 +30,7 @@ The :ref:`node ` should s .. literalinclude:: _include/envoy-dynamic-lds-demo.yaml :language: yaml :linenos: + :emphasize-lines: 1, 8-9, 28 ``resources`` - Clusters Discovery Service (CDS) ------------------------------------------------ @@ -37,6 +38,7 @@ The :ref:`node ` should s .. literalinclude:: _include/envoy-dynamic-cds-demo.yaml :language: yaml :linenos: + :emphasize-lines: 1, 10, 16-17 ``admin`` --------- From b49ebc446d29b185d25bc264784bde367aee0557 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Wed, 28 Oct 2020 15:38:07 +0000 Subject: [PATCH 06/24] docs/ Signed-off-by: Ryan Northey --- .../start/quick-start/configuration-dynamic-filesystem.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 768abc0f7251b..415b28eea5d66 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -25,7 +25,7 @@ The :ref:`node ` should s :emphasize-lines: 3-7 ``resources`` - Listeners Discovery Service (LDS) -------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: _include/envoy-dynamic-lds-demo.yaml :language: yaml @@ -33,7 +33,7 @@ The :ref:`node ` should s :emphasize-lines: 1, 8-9, 28 ``resources`` - Clusters Discovery Service (CDS) ------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: _include/envoy-dynamic-cds-demo.yaml :language: yaml From 96474444102132d57e33dbc89bfe3141a155cc1f Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 13:09:54 +0000 Subject: [PATCH 07/24] docs/ Signed-off-by: Ryan Northey --- .../configuration-dynamic-filesystem.rst | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 415b28eea5d66..f5e836e696f0e 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -3,6 +3,30 @@ Configuration: Dynamic from filesystem ====================================== +You can start Envoy with dynamic configuration that uses files as a form of +:ref:`Extensible discovery service (xDS) `. + +When the files are changed on the filesystem, Envoy will automatically update its configuration. + +At a minimum, you will need to start Envoy configured with the following sections: + +- :ref:`node ` to uniquely identify the proxy node. +- :ref:`dynamic_resources ` to tell Envoy where to find its + dynamic configuration. + +For the given example you will also need two dynamic configuration files: + +- :ref:`cds.yaml ` for clusters. +- :ref:`lds.yaml ` for listeners. + +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 +:download:`demo dynamic filesystem configuration file <_include/envoy-dynamic-filesystem-demo.yaml>`. + +.. _start_quick_start_dynamic_fs_node: + ``node`` -------- @@ -14,6 +38,8 @@ The :ref:`node ` should s :lines: 1-5 :emphasize-lines: 1-3 +.. _start_quick_start_dynamic_fs_dynamic_resources: + ``dynamic_resources`` --------------------- @@ -24,6 +50,8 @@ The :ref:`node ` should s :lineno-start: 3 :emphasize-lines: 3-7 +.. _start_quick_start_dynamic_fs_dynamic_lds: + ``resources`` - Listeners Discovery Service (LDS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -32,6 +60,8 @@ The :ref:`node ` should s :linenos: :emphasize-lines: 1, 8-9, 28 +.. _start_quick_start_dynamic_fs_dynamic_cds: + ``resources`` - Clusters Discovery Service (CDS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -40,6 +70,8 @@ The :ref:`node ` should s :linenos: :emphasize-lines: 1, 10, 16-17 +.. _start_quick_start_dynamic_fs_admin: + ``admin`` --------- From 6007309fd6b7a37c9f393a73f09c52f58368a425 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 13:36:10 +0000 Subject: [PATCH 08/24] docs/ Signed-off-by: Ryan Northey --- .../configuration-dynamic-filesystem.rst | 20 +++++++++++++++---- docs/root/start/quick-start/index.rst | 3 ++- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index f5e836e696f0e..5f4b461ef698a 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -43,6 +43,11 @@ The :ref:`node ` should s ``dynamic_resources`` --------------------- +The :ref:`dynamic_resources ` specify +where to load dynamic configuration. + +In this example, the configuration is provided by the ``yaml`` files set below. + .. literalinclude:: _include/envoy-dynamic-filesystem-demo.yaml :language: yaml :linenos: @@ -52,29 +57,36 @@ The :ref:`node ` should s .. _start_quick_start_dynamic_fs_dynamic_lds: -``resources`` - Listeners Discovery Service (LDS) +``resources`` - Listener discovery service (LDS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: _include/envoy-dynamic-lds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 1, 8-9, 28 + :emphasize-lines: 8-9, 28 .. _start_quick_start_dynamic_fs_dynamic_cds: -``resources`` - Clusters Discovery Service (CDS) +``resources`` - Cluster discovery service (CDS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: _include/envoy-dynamic-cds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 1, 10, 16-17 + :emphasize-lines: 10, 16-17 .. _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: diff --git a/docs/root/start/quick-start/index.rst b/docs/root/start/quick-start/index.rst index 2ab91d96155d9..566b82f0a084c 100644 --- a/docs/root/start/quick-start/index.rst +++ b/docs/root/start/quick-start/index.rst @@ -3,7 +3,8 @@ Quick start =========== -intro message +The quick start section takes you through basic operations with the Envoy server, and +provides an introduction to the types of configuration Envoy can be used with. .. toctree:: :maxdepth: 3 From 617fdb7dc1e6750efc06fcab15b5db0227d417a4 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 13:37:19 +0000 Subject: [PATCH 09/24] docs/ Signed-off-by: Ryan Northey --- .../root/start/quick-start/configuration-dynamic-filesystem.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 5f4b461ef698a..2e1417e7c4515 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -16,8 +16,8 @@ At a minimum, you will need to start Envoy configured with the following section For the given example you will also need two dynamic configuration files: -- :ref:`cds.yaml ` for clusters. - :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 retrieve stats or configuration information. From 5e6c29c0c0d1281e0c0d27a32360f6ce9edf6000 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 16:32:01 +0000 Subject: [PATCH 10/24] docs/ Signed-off-by: Ryan Northey --- .../_include/envoy-dynamic-cds-demo.yaml | 11 +++++++---- .../_include/envoy-dynamic-lds-demo.yaml | 3 +-- .../configuration-dynamic-filesystem.rst | 13 +++++++++++-- 3 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml index 5b58accbc71d6..9a4d656eeb833 100644 --- a/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml +++ b/docs/root/start/quick-start/_include/envoy-dynamic-cds-demo.yaml @@ -1,5 +1,3 @@ -version_info: "1" - resources: - "@type": type.googleapis.com/envoy.config.cluster.v3.Cluster name: example_proxy_cluster @@ -13,5 +11,10 @@ resources: - endpoint: address: socket_address: - address: service1 - port_value: 8080 + address: www.envoyproxy.io + port_value: 443 + transport_socket: + name: envoy.transport_sockets.tls + typed_config: + "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext + sni: www.envoyproxy.io diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml index 7febaca551362..1d07e44770b2d 100644 --- a/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml +++ b/docs/root/start/quick-start/_include/envoy-dynamic-lds-demo.yaml @@ -1,5 +1,3 @@ -version_info: "1" - resources: - "@type": type.googleapis.com/envoy.config.listener.v3.Listener name: listener_0 @@ -25,4 +23,5 @@ resources: - match: prefix: "/" route: + host_rewrite_literal: www.envoyproxy.io cluster: example_proxy_cluster diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 2e1417e7c4515..865830301f97f 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -60,20 +60,29 @@ In this example, the configuration is provided by the ``yaml`` files set below. ``resources`` - Listener discovery service (LDS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The following example of a :download:`dynamic LDS file <_include/envoy-dynamic-lds-demo.yaml>`, +configures an ``HTTP`` listener on port ``10000``. + +All paths are matched and routed to the ``service_envoyproxy_io`` cluster. + .. literalinclude:: _include/envoy-dynamic-lds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 8-9, 28 + :emphasize-lines: 5-7, 29 .. _start_quick_start_dynamic_fs_dynamic_cds: ``resources`` - Cluster discovery service (CDS) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In the following example of a :download:`dynamic CDS file <_include/envoy-dynamic-cds-demo.yaml>`, +the ``service_envoyproxy_io`` :ref:`cluster ` +proxies over ``TLS`` to https://www.envoyproxy.io. + .. literalinclude:: _include/envoy-dynamic-cds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 10, 16-17 + :emphasize-lines: 8, 14-15 .. _start_quick_start_dynamic_fs_admin: From c75e7d53180222ef795ad53ebf8eec66b856a368 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 16:43:43 +0000 Subject: [PATCH 11/24] docs/ Signed-off-by: Ryan Northey --- .../root/start/quick-start/configuration-dynamic-filesystem.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 865830301f97f..564c9ad755d52 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -68,7 +68,7 @@ All paths are matched and routed to the ``service_envoyproxy_io`` cluster. .. literalinclude:: _include/envoy-dynamic-lds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 5-7, 29 + :emphasize-lines: 6-7, 27 .. _start_quick_start_dynamic_fs_dynamic_cds: From 0c4bfe7bb23b1746de6d5bded6cf24fa7dea2695 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 17:13:18 +0000 Subject: [PATCH 12/24] docs/ Signed-off-by: Ryan Northey --- .../configuration-dynamic-filesystem.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 564c9ad755d52..6fbea8500a4db 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -44,7 +44,7 @@ The :ref:`node ` should s --------------------- The :ref:`dynamic_resources ` specify -where to load dynamic configuration. +where to load dynamic configuration from. In this example, the configuration is provided by the ``yaml`` files set below. @@ -57,26 +57,27 @@ In this example, the configuration is provided by the ``yaml`` files set below. .. _start_quick_start_dynamic_fs_dynamic_lds: -``resources`` - Listener discovery service (LDS) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``resources`` - :ref:`Listener discovery service (LDS) ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following example of a :download:`dynamic LDS file <_include/envoy-dynamic-lds-demo.yaml>`, -configures an ``HTTP`` listener on port ``10000``. +configures an ``HTTP`` :ref:`listener ` +on port ``10000``. All paths are matched and routed to the ``service_envoyproxy_io`` cluster. .. literalinclude:: _include/envoy-dynamic-lds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 6-7, 27 + :emphasize-lines: 6-7, 20-21, 24, 27 .. _start_quick_start_dynamic_fs_dynamic_cds: -``resources`` - Cluster discovery service (CDS) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``resources`` - :ref:`Cluster discovery service (CDS) ` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the following example of a :download:`dynamic CDS file <_include/envoy-dynamic-cds-demo.yaml>`, -the ``service_envoyproxy_io`` :ref:`cluster ` +the ``example_proxy_cluster`` :ref:`cluster ` proxies over ``TLS`` to https://www.envoyproxy.io. .. literalinclude:: _include/envoy-dynamic-cds-demo.yaml From 69e4c15ca2dced4dbfc4937c7a7060217c64c91c Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 17:47:17 +0000 Subject: [PATCH 13/24] docs/ Signed-off-by: Ryan Northey --- .../configuration-dynamic-filesystem.rst | 8 ++++--- docs/root/start/quick-start/next-steps.rst | 22 +++++++++++++++---- 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 6fbea8500a4db..47657e6a6fc60 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -64,12 +64,14 @@ The following example of a :download:`dynamic LDS file <_include/envoy-dynamic-l configures an ``HTTP`` :ref:`listener ` on port ``10000``. -All paths are matched and routed to the ``service_envoyproxy_io`` cluster. +All domains and paths are matched and routed to the ``service_envoyproxy_io`` cluster. + +The ``host`` headers are rewritten to ``www.envoyproxy.io`` .. literalinclude:: _include/envoy-dynamic-lds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 6-7, 20-21, 24, 27 + :emphasize-lines: 6-7, 20-21, 24, 26-27 .. _start_quick_start_dynamic_fs_dynamic_cds: @@ -83,7 +85,7 @@ proxies over ``TLS`` to https://www.envoyproxy.io. .. literalinclude:: _include/envoy-dynamic-cds-demo.yaml :language: yaml :linenos: - :emphasize-lines: 8, 14-15 + :emphasize-lines: 8, 14-15, 19-20 .. _start_quick_start_dynamic_fs_admin: diff --git a/docs/root/start/quick-start/next-steps.rst b/docs/root/start/quick-start/next-steps.rst index e6e9b4afb1a29..d5e6eb9c4064c 100644 --- a/docs/root/start/quick-start/next-steps.rst +++ b/docs/root/start/quick-start/next-steps.rst @@ -3,7 +3,21 @@ Next steps ========== -- Learn more about :ref:`using the Envoy Docker image ` -- Try out demo configurations in the :ref:`sandboxes ` -- Check out the :ref:`configuration generator ` and other - :ref:`Envoy tools ` +Setup a Docker deployment +------------------------- + +Learn more about :ref:`using the Envoy Docker image `. + +You can also :ref:`build your own Envoy and/or Docker image <>`. + +Run example sandboxes +--------------------- + +The provided :ref:`sandboxes ` are a great way to gain more experience in using Envoy, +and can be built upon model your own deployments. + +Build your Envoy configuration +------------------------------ + +Check out the :ref:`configuration generator ` and other +:ref:`Envoy tools ` for building Envoy configuration. From 176b86525243d72f1c94ce7b3f37fc0eb4c2e524 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 18:02:50 +0000 Subject: [PATCH 14/24] docs/ Signed-off-by: Ryan Northey --- docs/root/start/quick-start/next-steps.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/root/start/quick-start/next-steps.rst b/docs/root/start/quick-start/next-steps.rst index d5e6eb9c4064c..6625778f649f4 100644 --- a/docs/root/start/quick-start/next-steps.rst +++ b/docs/root/start/quick-start/next-steps.rst @@ -8,7 +8,7 @@ Setup a Docker deployment Learn more about :ref:`using the Envoy Docker image `. -You can also :ref:`build your own Envoy and/or Docker image <>`. +You can also :ref:`build your own Envoy and/or Docker image `. Run example sandboxes --------------------- From ebbc1e19a41d6c0d04a5ca753b6ccea81f426a7f Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Thu, 29 Oct 2020 18:26:03 +0000 Subject: [PATCH 15/24] docs/ Signed-off-by: Ryan Northey --- docs/root/start/quick-start/next-steps.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/root/start/quick-start/next-steps.rst b/docs/root/start/quick-start/next-steps.rst index 6625778f649f4..cadf47c0f6cdd 100644 --- a/docs/root/start/quick-start/next-steps.rst +++ b/docs/root/start/quick-start/next-steps.rst @@ -8,16 +8,16 @@ Setup a Docker deployment Learn more about :ref:`using the Envoy Docker image `. -You can also :ref:`build your own Envoy and/or Docker image `. +You can also :ref:`build your own Envoy and/or Docker image `. Run example sandboxes --------------------- The provided :ref:`sandboxes ` are a great way to gain more experience in using Envoy, -and can be built upon model your own deployments. +and can be used to model your own deployments. Build your Envoy configuration ------------------------------ Check out the :ref:`configuration generator ` and other -:ref:`Envoy tools ` for building Envoy configuration. +:ref:`Envoy tools ` for working with Envoy configuration. From 29f8d476323742cac8760217b338c4d9a1b256c3 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 06:23:08 +0000 Subject: [PATCH 16/24] docs/ Signed-off-by: Ryan Northey --- .../envoy-dynamic-control-plane-demo.yaml | 9 -------- .../configuration-dynamic-control-plane.rst | 23 ++----------------- 2 files changed, 2 insertions(+), 30 deletions(-) diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml index 2b0c443e6a11d..e1963a104ff40 100644 --- a/docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml +++ b/docs/root/start/quick-start/_include/envoy-dynamic-control-plane-demo.yaml @@ -32,15 +32,6 @@ static_resources: address: my-control-plane port_value: 18000 -layered_runtime: - layers: - - name: runtime-0 - rtds_layer: - name: runtime-0 - rtds_config: - resource_api_version: V3 - ads: {} - admin: access_log_path: /dev/null address: 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 985cce2f5ccfd..bc6e73791e6f1 100644 --- a/docs/root/start/quick-start/configuration-dynamic-control-plane.rst +++ b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst @@ -18,7 +18,6 @@ At a minimum, you will need to start Envoy configured with the following section - :ref:`node ` to uniquely identify the proxy node. - :ref:`dynamic_resources ` to tell Envoy which configurations should be updated dynamically - :ref:`static_resources ` to specify where Envoy should retrieve its configuration from. -- :ref:`layered_runtime ` to persist dynamically-provided configurations. You can also add an :ref:`admin ` section if you wish to monitor Envoy or retrieve stats or configuration information. @@ -74,24 +73,6 @@ The ``xds_cluster`` is configured to query a control plane at http://my-control- :lineno-start: 17 :emphasize-lines: 3-17 -.. _start_quick_start_dynamic_layered_runtime: - -``layered_runtime`` -------------------- - -A :ref:`layered_runtime ` is -required with an :ref:`rtds_layer ` -to persist configuration provided by the control plane. - -.. literalinclude:: _include/envoy-dynamic-control-plane-demo.yaml - :language: yaml - :linenos: - :lines: 33-44 - :lineno-start: 33 - :emphasize-lines: 3-10 - -.. _start_quick_start_dynamic_admin: - ``admin`` --------- @@ -105,8 +86,8 @@ endpoint to see how Envoy is currently configured. .. literalinclude:: _include/envoy-dynamic-control-plane-demo.yaml :language: yaml :linenos: - :lines: 42-49 - :lineno-start: 42 + :lines: 33-40 + :lineno-start: 33 :emphasize-lines: 3-8 .. warning:: From f093058b68b08e5f6abcd7319093257cdee07358 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 06:24:14 +0000 Subject: [PATCH 17/24] examples/ Signed-off-by: Ryan Northey --- examples/dynamic-config-cp/envoy.yaml | 9 --------- 1 file changed, 9 deletions(-) diff --git a/examples/dynamic-config-cp/envoy.yaml b/examples/dynamic-config-cp/envoy.yaml index 7d44f9ae63959..8f63bcfba0d65 100644 --- a/examples/dynamic-config-cp/envoy.yaml +++ b/examples/dynamic-config-cp/envoy.yaml @@ -32,15 +32,6 @@ static_resources: address: go-control-plane port_value: 18000 -layered_runtime: - layers: - - name: runtime-0 - rtds_layer: - name: runtime-0 - rtds_config: - resource_api_version: V3 - ads: {} - admin: access_log_path: /dev/null address: From b41fa1479640c1f9c875a30b30f3baeb1af31a46 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 06:38:23 +0000 Subject: [PATCH 18/24] docs/ Signed-off-by: Ryan Northey --- .../start/quick-start/configuration-dynamic-control-plane.rst | 2 ++ 1 file changed, 2 insertions(+) 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 bc6e73791e6f1..d7978156f5b88 100644 --- a/docs/root/start/quick-start/configuration-dynamic-control-plane.rst +++ b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst @@ -73,6 +73,8 @@ The ``xds_cluster`` is configured to query a control plane at http://my-control- :lineno-start: 17 :emphasize-lines: 3-17 +.. _start_quick_start_dynamic_admin: + ``admin`` --------- From 7f85f7fa08b325cd59ea4e28fbc1f4a6996ec065 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 07:29:34 +0000 Subject: [PATCH 19/24] docs/ Signed-off-by: Ryan Northey --- .../quick-start/configuration-dynamic-control-plane.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 d7978156f5b88..3896a9360fa2e 100644 --- a/docs/root/start/quick-start/configuration-dynamic-control-plane.rst +++ b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst @@ -3,8 +3,8 @@ Configuration: Dynamic from control plane ========================================= -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. +These instructions are 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 `_ or `Istiod `_. @@ -23,7 +23,7 @@ You can also add an :ref:`admin ` section if yo retrieve stats or configuration information. The following sections walk through the dynamic configuration provided in the -:download:`demo dynamic configuration file <_include/envoy-dynamic-control-plane-demo.yaml>`. +:download:`demo dynamic control plane configuration file <_include/envoy-dynamic-control-plane-demo.yaml>`. .. _start_quick_start_dynamic_node: From c99f194bd655a94a607f98ae3186b45db7291268 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 10:59:52 +0000 Subject: [PATCH 20/24] docs/ Signed-off-by: Ryan Northey --- .../start/quick-start/configuration-dynamic-filesystem.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index 47657e6a6fc60..cc7c4c74ba8c9 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -3,8 +3,8 @@ Configuration: Dynamic from filesystem ====================================== -You can start Envoy with dynamic configuration that uses files as a form of -:ref:`Extensible discovery service (xDS) `. +You can start Envoy with dynamic configuration by using files that implement the :ref:`xDS ` +protocol. When the files are changed on the filesystem, Envoy will automatically update its configuration. From a56d4b06373bff05cb45ab37accc30d704678fed Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 11:02:44 +0000 Subject: [PATCH 21/24] docs/ Signed-off-by: Ryan Northey --- .../start/quick-start/configuration-dynamic-control-plane.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 3896a9360fa2e..3ceb430abe366 100644 --- a/docs/root/start/quick-start/configuration-dynamic-control-plane.rst +++ b/docs/root/start/quick-start/configuration-dynamic-control-plane.rst @@ -7,7 +7,7 @@ These instructions are slightly more complex as you must also set up a control p configuration. There are a number of control planes compatible with Envoy's API such as `Gloo `_ -or `Istiod `_. +or `Istio `_. You may also wish to explore implementing your own control plane, in which case the `Go Control Plane `_ provides a reference implementation From e08efe961e82e60ec7e3c5f120891ff64811c3c1 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 11:08:08 +0000 Subject: [PATCH 22/24] docs/ Signed-off-by: Ryan Northey --- .../quick-start/configuration-dynamic-filesystem.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index cc7c4c74ba8c9..f7afcbfe35382 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -57,8 +57,10 @@ In this example, the configuration is provided by the ``yaml`` files set below. .. _start_quick_start_dynamic_fs_dynamic_lds: -``resources`` - :ref:`Listener discovery service (LDS) ` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``resources`` - listeners +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The linked ``lds_config`` should be an implementation of a :ref:`Listener discovery service (LDS) `. The following example of a :download:`dynamic LDS file <_include/envoy-dynamic-lds-demo.yaml>`, configures an ``HTTP`` :ref:`listener ` @@ -75,8 +77,10 @@ The ``host`` headers are rewritten to ``www.envoyproxy.io`` .. _start_quick_start_dynamic_fs_dynamic_cds: -``resources`` - :ref:`Cluster discovery service (CDS) ` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``resources`` - clusters +~~~~~~~~~~~~~~~~~~~~~~~~ + +The linked ``cds_config`` should be an implementation of a :ref:`Cluster discovery service (CDS) `. In the following example of a :download:`dynamic CDS file <_include/envoy-dynamic-cds-demo.yaml>`, the ``example_proxy_cluster`` :ref:`cluster ` From 9b5bf90a0e3d18b0b25c2833d061acce861aee98 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 12:07:39 +0000 Subject: [PATCH 23/24] docs/ Signed-off-by: Ryan Northey --- .../start/quick-start/configuration-dynamic-filesystem.rst | 4 ++++ docs/root/start/quick-start/configuration-static.rst | 1 - 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst index f7afcbfe35382..f6d55cf7a43b4 100644 --- a/docs/root/start/quick-start/configuration-dynamic-filesystem.rst +++ b/docs/root/start/quick-start/configuration-dynamic-filesystem.rst @@ -109,3 +109,7 @@ endpoint to see how Envoy is currently configured. :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 397fa5b40c794..74e539b529d0d 100644 --- a/docs/root/start/quick-start/configuration-static.rst +++ b/docs/root/start/quick-start/configuration-static.rst @@ -1,4 +1,3 @@ - .. _start_quick_start_static: Configuration: Static From fc4153fdd52f6ab9caa1155584271dc5228e4b15 Mon Sep 17 00:00:00 2001 From: Ryan Northey Date: Fri, 30 Oct 2020 12:24:09 +0000 Subject: [PATCH 24/24] docs/ Signed-off-by: Ryan Northey --- .../quick-start/_include/envoy-dynamic-filesystem-demo.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml b/docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml index 27587e0dbca40..728ceeddc8e5a 100644 --- a/docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml +++ b/docs/root/start/quick-start/_include/envoy-dynamic-filesystem-demo.yaml @@ -1,6 +1,6 @@ node: - id: id_1 - cluster: test + cluster: test-cluster + id: test-id dynamic_resources: cds_config: