Examples

Below we will use YAML representation of the config protos and a running example of a service proxying HTTP from 127.0.0.1:10000 to 127.0.0.2:1234.

Static

A minimal fully static bootstrap config is provided below:

  1. admin:
  2.   access_log_path: /tmp/admin_access.log
  3.   address:
  4.     socket_address: { address: 127.0.0.1, port_value: 9901 }
  6. static_resources:
  7.   listeners:
  8.   - name: listener_0
  9.     address:
  10.       socket_address: { address: 127.0.0.1, port_value: 10000 }
  11.     filter_chains:
  12.     - filters:
  13.       - name: envoy.http_connection_manager
  14.         typed_config:
  15.           "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
  16.           stat_prefix: ingress_http
  17.           codec_type: AUTO
  18.           route_config:
  19.             name: local_route
  20.             virtual_hosts:
  21.             - name: local_service
  22.               domains: ["*"]
  23.               routes:
  24.               - match: { prefix: "/" }
  25.                 route: { cluster: some_service }
  26.           http_filters:
  27.           - name: envoy.router
  28.   clusters:
  29.   - name: some_service
  30.     connect_timeout: 0.25s
  31.     type: STATIC
  32.     lb_policy: ROUND_ROBIN
  33.     load_assignment:
  34.       cluster_name: some_service
  35.       endpoints:
  36.       - lb_endpoints:
  37.         - endpoint:
  38.             address:
  39.               socket_address:
  40.                 address: 127.0.0.1
  41.                 port_value: 1234

Mostly static with dynamic EDS

A bootstrap config that continues from the above example with dynamic endpoint discovery via an EDS gRPC management server listening on 127.0.0.1:5678 is provided below:

  1. admin:
  2.   access_log_path: /tmp/admin_access.log
  3.   address:
  4.     socket_address: { address: 127.0.0.1, port_value: 9901 }
  6. static_resources:
  7.   listeners:
  8.   - name: listener_0
  9.     address:
  10.       socket_address: { address: 127.0.0.1, port_value: 10000 }
  11.     filter_chains:
  12.     - filters:
  13.       - name: envoy.http_connection_manager
  14.         typed_config:
  15.           "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
  16.           stat_prefix: ingress_http
  17.           codec_type: AUTO
  18.           route_config:
  19.             name: local_route
  20.             virtual_hosts:
  21.             - name: local_service
  22.               domains: ["*"]
  23.               routes:
  24.               - match: { prefix: "/" }
  25.                 route: { cluster: some_service }
  26.           http_filters:
  27.           - name: envoy.router
  28.   clusters:
  29.   - name: some_service
  30.     connect_timeout: 0.25s
  31.     lb_policy: ROUND_ROBIN
  32.     type: EDS
  33.     eds_cluster_config:
  34.       eds_config:
  35.         api_config_source:
  36.           api_type: GRPC
  37.           grpc_services:
  38.             envoy_grpc:
  39.               cluster_name: xds_cluster
  40.   - name: xds_cluster
  41.     connect_timeout: 0.25s
  42.     type: STATIC
  43.     lb_policy: ROUND_ROBIN
  44.     http2_protocol_options: {}
  45.     upstream_connection_options:
  46.       # configure a TCP keep-alive to detect and reconnect to the admin
  47.       # server in the event of a TCP socket half open connection
  48.       tcp_keepalive: {}
  49.     load_assignment:
  50.       cluster_name: xds_cluster
  51.       endpoints:
  52.       - lb_endpoints:
  53.         - endpoint:
  54.             address:
  55.               socket_address:
  56.                 address: 127.0.0.1
  57.                 port_value: 5678

Notice above that xds_cluster is defined to point Envoy at the management server. Even in an otherwise completely dynamic configurations, some static resources need to be defined to point Envoy at its xDS management server(s).

It’s important to set appropriate TCP Keep-Alive options in the tcp_keepalive block. This will help detect TCP half open connections to the xDS management server and re-establish a full connection.

In the above example, the EDS management server could then return a proto encoding of a DiscoveryResponse:

  1. version_info: "0"
  2. resources:
  3. - "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment
  4.   cluster_name: some_service
  5.   endpoints:
  6.   - lb_endpoints:
  7.     - endpoint:
  8.         address:
  9.           socket_address:
  10.             address: 127.0.0.2
  11.             port_value: 1234

The versioning and type URL scheme that appear above are explained in more detail in the streaming gRPC subscription protocol documentation.

Dynamic

A fully dynamic bootstrap configuration, in which all resources other than those belonging to the management server are discovered via xDS is provided below:

  1. admin:
  2.   access_log_path: /tmp/admin_access.log
  3.   address:
  4.     socket_address: { address: 127.0.0.1, port_value: 9901 }
  6. dynamic_resources:
  7.   lds_config:
  8.     api_config_source:
  9.       api_type: GRPC
  10.       grpc_services:
  11.         envoy_grpc:
  12.           cluster_name: xds_cluster
  13.   cds_config:
  14.     api_config_source:
  15.       api_type: GRPC
  16.       grpc_services:
  17.         envoy_grpc:
  18.           cluster_name: xds_cluster
  20. static_resources:
  21.   clusters:
  22.   - name: xds_cluster
  23.     connect_timeout: 0.25s
  24.     type: STATIC
  25.     lb_policy: ROUND_ROBIN
  26.     http2_protocol_options: {}
  27.     upstream_connection_options:
  28.       # configure a TCP keep-alive to detect and reconnect to the admin
  29.       # server in the event of a TCP socket half open connection
  30.       tcp_keepalive: {}
  31.     load_assignment:
  32.       cluster_name: xds_cluster
  33.       endpoints:
  34.       - lb_endpoints:
  35.         - endpoint:
  36.             address:
  37.               socket_address:
  38.                 address: 127.0.0.1
  39.                 port_value: 5678

The management server could respond to LDS requests with:

  1. version_info: "0"
  2. resources:
  3. - "@type": type.googleapis.com/envoy.api.v2.Listener
  4.   name: listener_0
  5.   address:
  6.     socket_address:
  7.       address: 127.0.0.1
  8.       port_value: 10000
  9.   filter_chains:
  10.   - filters:
  11.     - name: envoy.http_connection_manager
  12.       typed_config:
  13.         "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager
  14.         stat_prefix: ingress_http
  15.         codec_type: AUTO
  16.         rds:
  17.           route_config_name: local_route
  18.           config_source:
  19.             api_config_source:
  20.               api_type: GRPC
  21.               grpc_services:
  22.                 envoy_grpc:
  23.                   cluster_name: xds_cluster
  24.         http_filters:
  25.         - name: envoy.router

The management server could respond to RDS requests with:

  1. version_info: "0"
  2. resources:
  3. - "@type": type.googleapis.com/envoy.api.v2.RouteConfiguration
  4.   name: local_route
  5.   virtual_hosts:
  6.   - name: local_service
  7.     domains: ["*"]
  8.     routes:
  9.     - match: { prefix: "/" }
  10.       route: { cluster: some_service }

The management server could respond to CDS requests with:

  1. version_info: "0"
  2. resources:
  3. - "@type": type.googleapis.com/envoy.api.v2.Cluster
  4.   name: some_service
  5.   connect_timeout: 0.25s
  6.   lb_policy: ROUND_ROBIN
  7.   type: EDS
  8.   eds_cluster_config:
  9.     eds_config:
  10.       api_config_source:
  11.         api_type: GRPC
  12.         grpc_services:
  13.           envoy_grpc:
  14.             cluster_name: xds_cluster

The management server could respond to EDS requests with:

  1. version_info: "0"
  2. resources:
  3. - "@type": type.googleapis.com/envoy.api.v2.ClusterLoadAssignment
  4.   cluster_name: some_service
  5.   endpoints:
  6.   - lb_endpoints:
  7.     - endpoint:
  8.         address:
  9.           socket_address:
  10.             address: 127.0.0.2
  11.             port_value: 1234