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

The management server could respond to LDS requests with:

  1. version_info: "0"
  2. resources:
  3. - "@type": type.googleapis.com/envoy.config.listener.v3.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.filters.network.http_connection_manager
  12. typed_config:
  13. "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.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.filters.http.router

The management server could respond to RDS requests with:

  1. version_info: "0"
  2. resources:
  3. - "@type": type.googleapis.com/envoy.config.route.v3.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.config.cluster.v3.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.config.endpoint.v3.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