examples: Add dynamic configuration (control plane) sandbox

docs/root/start/sandboxes/_include/dynamic-configuration/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-configuration/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.rst

@@ -0,0 +1,175 @@
+.. _install_sandboxes_dynamic_configuration:
+
+Dynamic configuration
+=====================
+
+.. include:: _include/docker-env-setup.rst
+
+
+Step 3: Take a look at the proxy config
+***************************************
+
+.. literalinclude:: _include/dynamic-configuration/envoy.yaml
+   :language: yaml
+
+Step 4: Start the proxy container
+*********************************
+
+First lets build our containers and start the proxy container, and two backend HTTP echo servers.
+
+The go-control-plane has not yet been started.
+
+.. code-block:: console
+
+    $ pwd
+    envoy/examples/dynamic-configuration
+    $ docker-compose build --pull
+    $ docker-compose up -d proxy
+    $ docker-compose ps
+
+	      Name                            Command                 State                     Ports
+    ------------------------------------------------------------------------------------------------------------------------------
+    dynamic-configuration_proxy_1      /docker-entrypoint.sh /usr ... Up      0.0.0.0:10000->10000/tcp, 0.0.0.0:19000->19000/tcp
+    dynamic-configuration_service1_1   /bin/echo-server               Up      8080/tcp
+    dynamic-configuration_service2_1   /bin/echo-server               Up      8080/tcp
+
+Step 4: Check web response
+**************************
+
+Nothing is responding on port 10000
+
+.. code-block:: console
+
+   $ curl http://localhost:10000
+   curl: (56) Recv failure: Connection reset by peer
+
+If we config dump the ``static_clusters`` we should see the ``xds_cluster`` we configured for the control
+plane:
+
+.. code-block:: console
+
+   $ curl -s http://localhost:19000/config_dump  | jq '.configs[1].static_clusters'
+
+.. literalinclude:: _include/dynamic-configuration/response-config-cluster.json
+   :language: json
+
+Step 5: Start the go-control-plane
+**********************************
+
+Let's start up the go-control-plane.
+
+You may need to wait a moment or two for the service to become ``healthy``.
+
+.. code-block:: console
+
+    $ docker-compose up --build -d go-control-plane
+    $ docker-compose ps
+
+		Name                                Command                  State                    Ports
+    -----------------------------------------------------------------------------------------------------------------------------------------
+    dynamic-configuration_go-control-plane_1  bin/example -debug             Up (healthy)
+    dynamic-configuration_proxy_1             /docker-entrypoint.sh /usr ... Up            0.0.0.0:10000->10000/tcp, 0.0.0.0:19000->19000/tcp
+    dynamic-configuration_service1_1          /bin/echo-server               Up            8080/tcp
+    dynamic-configuration_service2_1          /bin/echo-server               Up            8080/tcp
+
+Step 5: Query the proxy
+***********************
+
+Once the control plane has started, we 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: service1
+   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 the proxy config again
+***********************************
+
+If we now ``config_dump`` the ``dynamic_active_clusters`` we should see the endpoint pointing
+to ``service1``
+
+.. code-block:: console
+
+   $ curl -s http://localhost:19000/config_dump  | jq '.configs[1].dynamic_active_clusters'
+
+.. literalinclude:: _include/dynamic-configuration/response-config-active-clusters.json
+   :language: json
+
+Step 5: Stop the go-control-plane
+*********************************
+
+Let's stop the go-control-plane:
+
+.. 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 5: Edit resource.go and restart the go-control-plane
+*********************************************************
+
+The example go-control-plane is started with a custom resource.go file which
+specifies the configuration provided to Envoy.
+
+If you edit this file and change the ``UpstreamHost`` from ``service1`` to ``service2``:
+
+.. literalinclude:: _include/dynamic-configuration/resource.go
+   :language: go
+   :lines: 33-40
+   :emphasize-lines: 6
+   :linenos:
+
+Further down in this file you must also change the configuration snapshot
+version number from ``"1"`` to ``"2"``:
+
+.. literalinclude:: _include/dynamic-configuration/resource.go
+   :language: go
+   :lineno-start: 167
+   :lines: 167-177
+   :emphasize-lines: 3
+   :linenos:
+
+Now rebuild and restart the go-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 to become ``healthy``.
+
+Step 5: Query the proxy
+***********************
+
+When you make
+
+.. code-block:: console
+
+   $ curl http://localhost:10000
+   Request served by service2
+
+   HTTP/1.1 GET /
+
+   Host: service1
+   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

docs/root/start/sandboxes/index.rst

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

examples/DEVELOPER.md

@@ -109,6 +109,17 @@ responds_without_header \
 
 `responds_without_header` can accept additional curl arguments like `responds_with`
 
+#### Utility functions: `wait_for`
+
+You can wait for some amount of time for a command to return 0
+
+The following example will wait for 20 seconds for a service ``my-service`` to become
+healthy.
+
+```bash
+wait_for 20 sh -c "docker-compose ps my-service | grep healthy | grep -v unhealthy"
+```
+
 ### Slow starting `docker` compositions
 
 Unless your example provides a way for ensuring that all containers are healthy by

examples/dynamic-configuration/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-configuration/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-configuration/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-configuration/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-configuration/envoy.yaml

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