examples: Add dynamic configuration (control plane) sandbox

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

@@ -0,0 +1,32 @@
+[
+  {
+    "version_info": "2",
+    "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-26T14:35:17.360Z"
+  }
+]

docs/root/start/sandboxes/_include/dynamic-config-cp/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/_include/dynamic-config-cp/response-config-cluster.json

@@ -0,0 +1,31 @@
+[
+  {
+    "cluster": {
+      "@type": "type.googleapis.com/envoy.api.v2.Cluster",
+      "name": "xds_cluster",
+      "type": "STRICT_DNS",
+      "connect_timeout": "1s",
+      "http2_protocol_options": {},
+      "load_assignment": {
+        "cluster_name": "xds_cluster",
+        "endpoints": [
+          {
+            "lb_endpoints": [
+              {
+                "endpoint": {
+                  "address": {
+                    "socket_address": {
+                      "address": "go-control-plane",
+                      "port_value": 18000
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        ]
+      }
+    },
+    "last_updated": "2020-10-25T20:20:54.897Z"
+  }
+]

docs/root/start/sandboxes/dynamic-configuration-control-plane.rst

@@ -0,0 +1,193 @@
+.. _install_sandboxes_dynamic_config_cp:
+
+Dynamic configuration (control plane)
+=====================================
+
+This example walks through configuring Envoy using the `Go Control Plane <https://github.com/envoyproxy/go-control-plane>`_
+reference implementation.
+
+It demonstrates how configuration provided to Envoy persists, even when the control plane is not available,
+and provides a trivial example of how to update Envoy's configuration dynamically.
+
+.. include:: _include/docker-env-setup.rst
+
+Change directory to ``examples/dynamic-config-cp`` in the Envoy repository.
+
+Step 3: Start the proxy container
+*********************************
+
+First build the containers and start the ``proxy`` container.
+
+This should also start two upstream ``HTTP`` echo servers, ``service1`` and ``service2``.
+
+The control plane has not yet been started.
+
+.. code-block:: console
+
+    $ pwd
+    envoy/examples/dynamic-config-cp
+    $ docker-compose build --pull
+    $ docker-compose up -d proxy
+    $ docker-compose ps
+
+           Name                            Command                State                     Ports
+    ------------------------------------------------------------------------------------------------------------------------
+    dynamic-config-cp_proxy_1      /docker-entrypoint.sh /usr ... Up      0.0.0.0:10000->10000/tcp, 0.0.0.0:19000->19000/tcp
+    dynamic-config-cp_service1_1   /bin/echo-server               Up      8080/tcp
+    dynamic-config-cp_service2_1   /bin/echo-server               Up      8080/tcp
+
+Step 4: Check initial config and web response
+*********************************************
+
+As we have not yet started the control plane, nothing should be responding on port ``10000``.
+
+.. code-block:: console
+
+   $ curl http://localhost:10000
+   curl: (56) Recv failure: Connection reset by peer
+
+Dump the proxy's ``static_clusters`` configuration and you should see the cluster named ``xds_cluster``
+configured for the control plane:
+
+.. code-block:: console
+
+   $ curl -s http://localhost:19000/config_dump  | jq '.configs[1].static_clusters'
+
+.. literalinclude:: _include/dynamic-config-cp/response-config-cluster.json
+   :language: json
+   :emphasize-lines: 10, 18-19
+
+No ``dynamic_active_clusters`` have been configured yet:
+
+.. code-block:: console
+
+   $ curl -s http://localhost:19000/config_dump  | jq '.configs[1].dynamic_active_clusters'
+   null
+
+Step 5: Start the control plane
+*******************************
+
+Start up the ``go-control-plane`` service.
+
+You may need to wait a moment or two for it to become ``healthy``.
+
+.. code-block:: console
+
+    $ docker-compose up --build -d go-control-plane
+    $ docker-compose ps
+
+            Name                                Command                  State                    Ports
+    -------------------------------------------------------------------------------------------------------------------------------------
+    dynamic-config-cp_go-control-plane_1  bin/example -debug             Up (healthy)
+    dynamic-config-cp_proxy_1             /docker-entrypoint.sh /usr ... Up            0.0.0.0:10000->10000/tcp, 0.0.0.0:19000->19000/tcp
+    dynamic-config-cp_service1_1          /bin/echo-server               Up            8080/tcp
+    dynamic-config-cp_service2_1          /bin/echo-server               Up            8080/tcp
+
+Step 6: Query the proxy
+***********************
+
+Once the control plane has started and is ``healthy``, you should be able to make a request to port ``10000``,
+which will be served by ``service1``.
+
+.. code-block:: console
+
+   $ curl http://localhost:10000
+   Request served by service1
+
+   HTTP/1.1 GET /
+
+   Host: localhost:10000
+   Accept: */*
+   X-Forwarded-Proto: http
+   X-Request-Id: 1d93050e-f39c-4602-90f8-a124d6e78d26
+   X-Envoy-Expected-Rq-Timeout-Ms: 15000
+   Content-Length: 0
+   User-Agent: curl/7.72.0
+
+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``, and a version of ``1``.
+
+.. code-block:: console
+
+   $ curl -s http://localhost:19000/config_dump  | jq '.configs[1].dynamic_active_clusters'
+
+.. literalinclude:: _include/dynamic-config-cp/response-config-active-clusters.json
+   :language: json
+   :emphasize-lines: 3, 11, 19-20
+
+Step 6: Stop the control plane
+******************************
+
+Stop the ``go-control-plane`` service:
+
+.. code-block:: console
+
+    $ docker-compose stop go-control-plane
+
+The Envoy proxy should continue proxying responses from ``service1``.
+
+.. code-block:: console
+
+   $ curl http://localhost:10000 | grep "served by"
+   Request served by service1
+
+Step 7: Edit resource.go and restart the go-control-plane
+*********************************************************
+
+The example setup starts `go-control-plane <https://github.com/envoyproxy/go-control-plane>`_
+with a custom :download:`resource.go <_include/dynamic-config-cp/resource.go>` file which
+specifies the configuration provided to Envoy.
+
+Update this to have Envoy proxy instead to ``service2``.
+
+Edit ``resource.go`` in the dynamic configuration example folder and change the ``UpstreamHost``
+from ``service1`` to ``service2``:
+
+.. literalinclude:: _include/dynamic-config-cp/resource.go
+   :language: go
+   :lines: 33-40
+   :lineno-start: 33
+   :emphasize-lines: 6
+   :linenos:
+
+Further down in this file you must also change the configuration snapshot version number from
+``"1"`` to ``"2"`` to ensure Envoy sees the configuration as newer:
+
+.. literalinclude:: _include/dynamic-config-cp/resource.go
+   :language: go
+   :lineno-start: 164
+   :lines: 164-174
+   :emphasize-lines: 3
+   :linenos:
+
+Now rebuild and restart the control plane:
+
+.. code-block:: console
+
+    $ docker-compose up --build -d go-control-plane
+
+You may need to wait a moment or two for the ``go-control-plane`` service to become ``healthy`` again.
+
+Step 8: Check Envoy uses the updated configuration
+**************************************************
+
+Now when you make a request to the proxy it should be served by the ``service2`` upstream service.
+
+.. code-block:: console
+
+   $ curl http://localhost:10000 | grep "served by"
+   Request served by service2
+
+Dumping the ``dynamic_active_clusters`` you should see the cluster configuration now has a version
+of ``2``, and ``example_proxy_cluster`` is configured to proxy to ``service2``:
+
+.. code-block:: console
+
+   $ curl -s http://localhost:19000/config_dump  | jq '.configs[1].dynamic_active_clusters'
+
+.. literalinclude:: _include/dynamic-config-cp/response-config-active-clusters-updated.json
+   :language: json
+   :emphasize-lines: 3, 11, 19-20

docs/root/start/sandboxes/index.rst

@@ -14,6 +14,7 @@ features. The following sandboxes are available:
     cache
     cors
     csrf
+    dynamic-configuration-control-plane
     ext_authz
     fault_injection
     front_proxy

examples/dynamic-config-cp/Dockerfile-control-plane

@@ -0,0 +1,7 @@
+FROM golang
+
+RUN apt-get -y update && apt-get install -y -qq --no-install-recommends netcat
+RUN git clone https://github.com/envoyproxy/go-control-plane
+ADD ./resource.go /go/go-control-plane/internal/example/resource.go
+RUN cd go-control-plane && make bin/example
+WORKDIR /go/go-control-plane

examples/dynamic-config-cp/Dockerfile-proxy

@@ -0,0 +1,6 @@
+FROM envoyproxy/envoy-dev:latest
+
+RUN apt-get -y update && apt-get install -y -qq --no-install-recommends netcat
+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-cp/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-control-plane.html).

examples/dynamic-config-cp/docker-compose.yaml

@@ -0,0 +1,29 @@
+version: "3.7"
+services:
+
+  proxy:
+    build:
+      context: .
+      dockerfile: Dockerfile-proxy
+    depends_on:
+      - service1
+      - service2
+    ports:
+      - 10000:10000
+      - 19000:19000
+
+  service1:
+    image: jmalloc/echo-server
+    hostname: service1
+
+  service2:
+    image: jmalloc/echo-server
+    hostname: service2
+
+  go-control-plane:
+    build:
+      context: .
+      dockerfile: Dockerfile-control-plane
+    command: bin/example -debug
+    healthcheck:
+      test: nc -zv localhost 18000

examples/dynamic-config-cp/envoy.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: 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:
+    socket_address:
+      address: 0.0.0.0
+      port_value: 19000