Dynamic configuration (filesystem)

Requirements

Sandbox environment

Setup your sandbox environment with Docker and Docker Compose, and clone the Envoy repository with Git.

curl

Used to make HTTP requests.

jq

Parse json output from the upstream echo servers.

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.

Step 1: Start the proxy container

Change directory to examples/dynamic-config-fs in the Envoy repository.

Build and start the containers.

This should also start two upstream HTTP echo servers, service1 and service2.

  1. $ pwd
  2. envoy/examples/dynamic-config-fs
  3. $ docker-compose build --pull
  4. $ docker-compose up -d
  5. $ docker-compose ps
  7.        Name                            Command                State                     Ports
  8. ------------------------------------------------------------------------------------------------------------------------
  9. dynamic-config-fs_proxy_1      /docker-entrypoint.sh /usr ... Up      0.0.0.0:10000->10000/tcp, 0.0.0.0:19000->19000/tcp
  10. dynamic-config-fs_service1_1   /bin/echo-server               Up      8080/tcp
  11. dynamic-config-fs_service2_1   /bin/echo-server               Up      8080/tcp

Step 2: Check web response

You should be able to make a request to port 10000, which will be served by service1.

  1. $ curl -s http://localhost:10000
  2. Request served by service1
  4. HTTP/2.0 GET /
  6. Host: localhost:10000
  7. User-Agent: curl/7.72.0
  8. Accept: */*
  9. X-Forwarded-Proto: http
  10. X-Request-Id: 6672902d-56ca-456c-be6a-992a603cab9a
  11. X-Envoy-Expected-Rq-Timeout-Ms: 15000

Step 3: 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.

  1. $ curl -s http://localhost:19000/config_dump | jq -r '.configs[1].dynamic_active_clusters'
  1. [
  2.   {
  3.     "cluster": {
  4.       "@type": "type.googleapis.com/envoy.config.cluster.v3.Cluster",
  5.       "name": "example_proxy_cluster",
  6.       "type": "LOGICAL_DNS",
  7.       "connect_timeout": "5s",
  8.       "dns_lookup_family": "V4_ONLY",
  9.       "load_assignment": {
  10.         "cluster_name": "example_proxy_cluster",
  11.         "endpoints": [
  12.           {
  13.             "lb_endpoints": [
  14.               {
  15.                 "endpoint": {
  16.                   "address": {
  17.                     "socket_address": {
  18.                       "address": "service1",
  19.                       "port_value": 8080
  20.                     }
  21.                   }
  22.                 }
  23.               }
  24.             ]
  25.           }
  26.         ]
  27.       }
  28.     },
  29.     "last_updated": "2020-10-25T20:37:05.838Z"
  30.   }
  31. ]

Step 4: Replace cds.yaml inside the container to update upstream cluster

The example setup provides Envoy with two dynamic configuration files:

Edit cds.yaml inside the container and change the cluster address from service1 to service2:

  1.  6    cluster_name: example_proxy_cluster
  2.  7    endpoints:
  3.  8    - lb_endpoints:
  4.  9      - endpoint:
  5. 10          address:
  6. 11            socket_address:
  7. 12              address: service1
  8. 13              port_value: 8080

You can do this using sed inside the container:

  1. docker-compose exec -T proxy sed -i s/service1/service2/ /var/lib/envoy/cds.yaml

Note

The above example uses sed -i, which works as an inplace edit as sed does copy, edit and move in order to do this.

Step 5: Check Envoy uses updated configuration

Checking the web response again, the request should now be handled by service2:

  1. $ curl http://localhost:10000 | grep "served by"
  2. Request served by service2

Dumping the dynamic_active_clusters, the example_proxy_cluster should now be configured to proxy to service2:

  1. $ curl -s http://localhost:19000/config_dump | jq -r '.configs[1].dynamic_active_clusters'
  1. [
  2.   {
  3.     "cluster": {
  4.       "@type": "type.googleapis.com/envoy.config.cluster.v3.Cluster",
  5.       "name": "example_proxy_cluster",
  6.       "type": "LOGICAL_DNS",
  7.       "connect_timeout": "5s",
  8.       "dns_lookup_family": "V4_ONLY",
  9.       "load_assignment": {
  10.         "cluster_name": "example_proxy_cluster",
  11.         "endpoints": [
  12.           {
  13.             "lb_endpoints": [
  14.               {
  15.                 "endpoint": {
  16.                   "address": {
  17.                     "socket_address": {
  18.                       "address": "service2",
  19.                       "port_value": 8080
  20.                     }
  21.                   }
  22.                 }
  23.               }
  24.             ]
  25.           }
  26.         ]
  27.       }
  28.     },
  29.     "last_updated": "2020-10-25T20:37:05.838Z"
  30.   }
  31. ]

See also

Dynamic configuration (filesystem) quick start guide

Quick start guide to filesystem-based dynamic configuration of Envoy.

Envoy admin quick start guide

Quick start guide to the Envoy admin interface.

Dynamic configuration (control plane) sandbox

Configure Envoy dynamically with the Go Control Plane.