examples: Add dynamic configuration (filesystem) sandbox

.azure-pipelines/pipelines.yml

@@ -167,7 +167,7 @@ stages:
               AZP_BRANCH: $(Build.SourceBranch)
 
   - stage: linux_x64
-    dependsOn: ["precheck"]
+    dependsOn: []
     # For post-submit builds, continue even if precheck fails
     condition: and(not(canceled()), or(succeeded(), eq(variables['PostSubmit'], true)))
     jobs:
@@ -181,7 +181,7 @@ stages:
               ciTarget: bazel.release
 
   - stage: linux_arm64
-    dependsOn: ["precheck"]
+    dependsOn: []
     # For post-submit builds, continue even if precheck fails
     condition: and(not(canceled()), or(succeeded(), eq(variables['PostSubmit'], true)))
     jobs:

docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters-updated.json

@@ -0,0 +1,32 @@
+[
+  {
+    "version_info": "1",
+    "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"
+  }
+]

docs/root/start/sandboxes/_include/dynamic-config-fs/response-config-active-clusters.json

@@ -0,0 +1,32 @@
+[
+  {
+    "version_info": "1",
+    "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"
+  }
+]

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: 11, 19-20
+
+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) <config_cluster_manager_cds>`.
+- :download:`configs/lds.yaml <_include/dynamic-config-fs/configs/lds.yaml>` to provide a :ref:`Listener
+  discovery service (CDS) <config_listeners_lds>`.
+
+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: 9-17
+   :lineno-start: 9
+   :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 cluster ``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: 11, 19-20

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

examples/BUILD

@@ -18,6 +18,7 @@ filegroup(
         ],
         exclude = [
             "cache/responses.yaml",
+            "dynamic-config-fs/**/*",
             "jaeger-native-tracing/*",
             "**/*docker-compose*.yaml",
         ],

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"]

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/postgres.html).

examples/dynamic-config-fs/configs/cds.yaml

@@ -0,0 +1,17 @@
+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

examples/dynamic-config-fs/configs/lds.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
+        http_filters:
+        - name: envoy.router
+        route_config:
+          name: local_route
+          virtual_hosts:
+          - name: local_service
+            domains:
+            - "*"
+            routes:
+            - match:
+                prefix: "/"
+              route:
+                cluster: example_proxy_cluster

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

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

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"'