diff --git a/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters-updated.json b/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters-updated.json new file mode 100644 index 000000000000..43b676e72d66 --- /dev/null +++ b/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters-updated.json @@ -0,0 +1,31 @@ +[ + { + "cluster": { + "@type": "type.googleapis.com/envoy.config.cluster.v3.Cluster", + "name": "example_proxy_cluster", + "type": "LOGICAL_DNS", + "connect_timeout": "5s", + "dns_lookup_family": "V4_ONLY", + "load_assignment": { + "cluster_name": "example_proxy_cluster", + "endpoints": [ + { + "lb_endpoints": [ + { + "endpoint": { + "address": { + "socket_address": { + "address": "service2", + "port_value": 8080 + } + } + } + } + ] + } + ] + } + }, + "last_updated": "2020-10-25T20:37:05.838Z" + } +] diff --git a/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters.json b/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters.json new file mode 100644 index 000000000000..3813a9a9c56c --- /dev/null +++ b/docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters.json @@ -0,0 +1,31 @@ +[ + { + "cluster": { + "@type": "type.googleapis.com/envoy.config.cluster.v3.Cluster", + "name": "example_proxy_cluster", + "type": "LOGICAL_DNS", + "connect_timeout": "5s", + "dns_lookup_family": "V4_ONLY", + "load_assignment": { + "cluster_name": "example_proxy_cluster", + "endpoints": [ + { + "lb_endpoints": [ + { + "endpoint": { + "address": { + "socket_address": { + "address": "service1", + "port_value": 8080 + } + } + } + } + ] + } + ] + } + }, + "last_updated": "2020-10-25T20:37:05.838Z" + } +] diff --git a/docs/root/start/sandboxes/dynamic-configuration-filesystem.rst b/docs/root/start/sandboxes/dynamic-configuration-filesystem.rst new file mode 100644 index 000000000000..d71bee0e9673 --- /dev/null +++ b/docs/root/start/sandboxes/dynamic-configuration-filesystem.rst @@ -0,0 +1,122 @@ +.. _install_sandboxes_dynamic_config_fs: + +Dynamic configuration (filesystem) +================================== + +This example walks through configuring Envoy using filesystem-based dynamic configuration. + +It demonstrates how configuration provided to Envoy dynamically can be updated without +restarting the server. + +.. include:: _include/docker-env-setup.rst + +Change directory to ``examples/dynamic-config-fs`` in the Envoy repository. + +Step 3: Start the proxy container +********************************* + +.. note:: + + If you are running on a system with strict ``umask`` you will need to ``chmod`` the dynamic config + files which are mounted into the container: + + .. code-block:: console + + $ umask + 027 + $ pwd + envoy/examples/dynamic-config-fs + $ chmod go+r configs/* + $ chmod go+x configs + +Build and start the containers. + +This should also start two upstream ``HTTP`` echo servers, ``service1`` and ``service2``. + +.. code-block:: console + + $ pwd + envoy/examples/dynamic-config-fs + $ docker-compose build --pull + $ docker-compose up -d + $ docker-compose ps + + Name Command State Ports + ------------------------------------------------------------------------------------------------------------------------ + dynamic-config-fs_proxy_1 /docker-entrypoint.sh /usr ... Up 0.0.0.0:10000->10000/tcp, 0.0.0.0:19000->19000/tcp + dynamic-config-fs_service1_1 /bin/echo-server Up 8080/tcp + dynamic-config-fs_service2_1 /bin/echo-server Up 8080/tcp + +Step 4: Check web response +************************** + +You should be able to make a request to port ``10000``, which will be served by ``service1``. + +.. code-block:: console + + $ curl -s http://localhost:10000 + Request served by service1 + + HTTP/2.0 GET / + + Host: localhost:10000 + User-Agent: curl/7.72.0 + Accept: */* + X-Forwarded-Proto: http + X-Request-Id: 6672902d-56ca-456c-be6a-992a603cab9a + X-Envoy-Expected-Rq-Timeout-Ms: 15000 + +Step 5: Dump Envoy's ``dynamic_active_clusters`` config +******************************************************* + +If you now dump the proxy’s ``dynamic_active_clusters`` configuration, you should see it is configured with +the ``example_proxy_cluster`` pointing to ``service1``. + +.. code-block:: console + + $ curl -s http://localhost:19000/config_dump | jq -r '.configs[1].dynamic_active_clusters' + +.. literalinclude:: _include/dynamic-config-fs/response-config-active-clusters.json + :language: json + :emphasize-lines: 10, 18-19 + +Step 5: Edit ``configs/cds.yaml`` file to update upstream cluster +***************************************************************** + +The example setup provides two dynamic configuration files: + +- :download:`configs/cds.yaml <_include/dynamic-config-fs/configs/cds.yaml>` to provide a :ref:`Cluster + discovery service (CDS) `. +- :download:`configs/lds.yaml <_include/dynamic-config-fs/configs/lds.yaml>` to provide a :ref:`Listener + discovery service (CDS) `. + +Edit ``configs/cds.yaml`` in the dynamic configuration example folder and change the cluster address +from ``service1`` to ``service2``: + +.. literalinclude:: _include/dynamic-config-fs/configs/cds.yaml + :language: yaml + :linenos: + :lines: 7-15 + :lineno-start: 7 + :emphasize-lines: 8 + +Step 6: Check Envoy uses updated configuration +********************************************** + +Checking the web response again, the request should now be handled by ``service2``: + +.. code-block:: console + + $ curl http://localhost:10000 | grep "served by" + Request served by service2 + +Dumping the ``dynamic_active_clusters``, the ``example_proxy_cluster`` should now be +configured to proxy to ``service2``: + +.. code-block:: console + + $ curl -s http://localhost:19000/config_dump jq -r '.configs[1].dynamic_active_clusters' + +.. literalinclude:: _include/dynamic-config-fs/response-config-active-clusters-updated.json + :language: json + :emphasize-lines: 10, 18-19 diff --git a/docs/root/start/sandboxes/index.rst b/docs/root/start/sandboxes/index.rst index 550776cd2503..88db6644e856 100644 --- a/docs/root/start/sandboxes/index.rst +++ b/docs/root/start/sandboxes/index.rst @@ -14,6 +14,7 @@ features. The following sandboxes are available: cache cors csrf + dynamic-configuration-filesystem dynamic-configuration-control-plane ext_authz fault_injection diff --git a/examples/BUILD b/examples/BUILD index f5fdff5710a4..59d945583b06 100644 --- a/examples/BUILD +++ b/examples/BUILD @@ -18,6 +18,7 @@ filegroup( ], exclude = [ "cache/responses.yaml", + "dynamic-config-fs/**/*", "jaeger-native-tracing/*", "**/*docker-compose*.yaml", ], diff --git a/examples/dynamic-config-fs/Dockerfile-proxy b/examples/dynamic-config-fs/Dockerfile-proxy new file mode 100644 index 000000000000..f70f44311461 --- /dev/null +++ b/examples/dynamic-config-fs/Dockerfile-proxy @@ -0,0 +1,5 @@ +FROM envoyproxy/envoy-dev:latest + +COPY ./envoy.yaml /etc/envoy.yaml +RUN chmod go+r /etc/envoy.yaml +CMD ["/usr/local/bin/envoy", "-c /etc/envoy.yaml", "-l", "debug"] diff --git a/examples/dynamic-config-fs/README.md b/examples/dynamic-config-fs/README.md new file mode 100644 index 000000000000..3cb1ed49d940 --- /dev/null +++ b/examples/dynamic-config-fs/README.md @@ -0,0 +1,2 @@ +To learn about this sandbox and for instructions on how to run it please head over +to the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/dynamic-configuration-filesystem.html). diff --git a/examples/dynamic-config-fs/configs/cds.yaml b/examples/dynamic-config-fs/configs/cds.yaml new file mode 100644 index 000000000000..3f661da7d7ab --- /dev/null +++ b/examples/dynamic-config-fs/configs/cds.yaml @@ -0,0 +1,15 @@ +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/examples/dynamic-config-fs/configs/lds.yaml b/examples/dynamic-config-fs/configs/lds.yaml new file mode 100644 index 000000000000..4770f538ac25 --- /dev/null +++ b/examples/dynamic-config-fs/configs/lds.yaml @@ -0,0 +1,26 @@ +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 + http_filters: + - name: envoy.router + route_config: + name: local_route + virtual_hosts: + - name: local_service + domains: + - "*" + routes: + - match: + prefix: "/" + route: + cluster: example_proxy_cluster diff --git a/examples/dynamic-config-fs/docker-compose.yaml b/examples/dynamic-config-fs/docker-compose.yaml new file mode 100644 index 000000000000..b3aed8c7e8ad --- /dev/null +++ b/examples/dynamic-config-fs/docker-compose.yaml @@ -0,0 +1,23 @@ +version: "3.7" +services: + + proxy: + build: + context: . + dockerfile: Dockerfile-proxy + depends_on: + - service1 + - service2 + ports: + - 10000:10000 + - 19000:19000 + volumes: + - ./configs:/var/lib/envoy + + service1: + image: jmalloc/echo-server + hostname: service1 + + service2: + image: jmalloc/echo-server + hostname: service2 diff --git a/examples/dynamic-config-fs/envoy.yaml b/examples/dynamic-config-fs/envoy.yaml new file mode 100644 index 000000000000..27587e0dbca4 --- /dev/null +++ b/examples/dynamic-config-fs/envoy.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/examples/dynamic-config-fs/verify.sh b/examples/dynamic-config-fs/verify.sh new file mode 100755 index 000000000000..1799bd9575f9 --- /dev/null +++ b/examples/dynamic-config-fs/verify.sh @@ -0,0 +1,32 @@ +#!/bin/bash -e + +export NAME=dynamic-config-fs + +chmod go+r configs/* +chmod go+rx configs + +# shellcheck source=examples/verify-common.sh +. "$(dirname "${BASH_SOURCE[0]}")/../verify-common.sh" + +run_log "Check for response comes from service1 upstream" +responds_with \ + "Request served by service1" \ + http://localhost:10000 + +run_log "Check config for active clusters pointing to service1" +curl -s http://localhost:19000/config_dump \ + | jq -r '.configs[1].dynamic_active_clusters' \ + | grep '"address": "service1"' + +run_log "Set upstream to service2" +sed -i s/service1/service2/ configs/cds.yaml + +run_log "Check for response comes from service2 upstream" +responds_with \ + "Request served by service2" \ + http://localhost:10000 + +run_log "Check config for active clusters pointing to service2" +curl -s http://localhost:19000/config_dump \ + | jq -r '.configs[1].dynamic_active_clusters' \ + | grep '"address": "service2"'