Configuration: Dynamic from filesystem

You can start Envoy with dynamic configuration by using files that implement the xDS protocol.

When the files are changed on the filesystem, Envoy will automatically update its configuration.

Note

Envoy only updates when the configuration file is replaced by a file move, and not when the file is edited in place.

It is implemented this way to ensure configuration consistency.

At a minimum, you will need to start Envoy configured with the following sections:

  • node to uniquely identify the proxy node.

  • dynamic_resources to tell Envoy where to find its dynamic configuration.

For the given example you will also need two dynamic configuration files:

You can also add an admin section if you wish to monitor Envoy or retrieve stats or configuration information.

The following sections walk through the dynamic configuration provided in the demo dynamic filesystem configuration file.

node

The node should specify cluster and id.

envoy-dynamic-filesystem-demo.yaml
1node:
2  cluster: test-cluster
3  id: test-id
4
5dynamic_resources:
6  cds_config:
7    resource_api_version: V3

dynamic_resources

The dynamic_resources specify where to load dynamic configuration from.

In this example, the configuration is provided by the yaml files set below.

envoy-dynamic-filesystem-demo.yaml
 3  id: test-id
 4
 5dynamic_resources:
 6  cds_config:
 7    resource_api_version: V3
 8    path: /var/lib/envoy/cds.yaml
 9  lds_config:
10    resource_api_version: V3
11    path: /var/lib/envoy/lds.yaml

resources - listeners

The linked lds_config should be an implementation of a Listener discovery service (LDS).

The following example of a dynamic LDS file, configures an HTTP listener on port 10000.

All domains and paths are matched and routed to the service_envoyproxy_io cluster.

The host headers are rewritten to www.envoyproxy.io

envoy-dynamic-lds-demo.yaml
 1resources:
 2- "@type": type.googleapis.com/envoy.config.listener.v3.Listener
 3  name: listener_0
 4  address:
 5    socket_address:
 6      address: 0.0.0.0
 7      port_value: 10000
 8  filter_chains:
 9  - filters:
10    - name: envoy.http_connection_manager
11      typed_config:
12        "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
13        stat_prefix: ingress_http
14        http_filters:
15        - name: envoy.router
16          typed_config:
17            "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
18        route_config:
19          name: local_route
20          virtual_hosts:
21          - name: local_service
22            domains:
23            - "*"
24            routes:
25            - match:
26                prefix: "/"
27              route:
28                host_rewrite_literal: www.envoyproxy.io
29                cluster: example_proxy_cluster

resources - clusters

The linked cds_config should be an implementation of a Cluster discovery service (CDS).

In the following example of a dynamic CDS file, the example_proxy_cluster cluster proxies over TLS to https://www.envoyproxy.io.

envoy-dynamic-cds-demo.yaml
 1resources:
 2- "@type": type.googleapis.com/envoy.config.cluster.v3.Cluster
 3  name: example_proxy_cluster
 4  type: STRICT_DNS
 5  typed_extension_protocol_options:
 6    envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
 7      "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
 8      explicit_http_config:
 9        http2_protocol_options: {}
10  load_assignment:
11    cluster_name: example_proxy_cluster
12    endpoints:
13    - lb_endpoints:
14      - endpoint:
15          address:
16            socket_address:
17              address: www.envoyproxy.io
18              port_value: 443
19  transport_socket:
20    name: envoy.transport_sockets.tls
21    typed_config:
22      "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
23      sni: www.envoyproxy.io

See also

atomic swaps

Details about how runtime configuration is updated.