From 54119f3225af89b3449764c91033beee71c55a9f Mon Sep 17 00:00:00 2001 From: Blake Covarrubias Date: Mon, 2 May 2022 11:25:59 -0700 Subject: [PATCH] docs: Add example Envoy escape hatch configs (#12764) Add example escape hatch configurations for all supported override types. --- .../content/docs/connect/proxies/envoy.mdx | 381 +++++++++++++++++- 1 file changed, 377 insertions(+), 4 deletions(-) diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 0262ede404..5374e58648 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -386,6 +386,8 @@ field set to the appropriate type (for example For example, given a tracing config: + + ```json { "http": { @@ -401,6 +403,8 @@ For example, given a tracing config: } ``` + + JSON escape the value of `tracing` into a string, for example using [https://codebeautify.org/json-escape-unescape](https://codebeautify.org/json-escape-unescape), or using [jq](https://stedolan.github.io/jq/). @@ -469,10 +473,39 @@ definition](/docs/connect/registration/service-registration) or - `envoy_extra_static_clusters_json` - Specifies one or more [Envoy clusters][pb-cluster] that will be appended to the array of [static clusters](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-staticresources-clusters) - in the bootstrap config. This allows adding custom clusters for tracing sinks - for example. For a single cluster just encode a single object, for multiple, - they should be comma separated with no trailing comma suitable for - interpolating directly into a JSON array inside the braces. + in the bootstrap config. This enables you to add custom clusters for tracing sinks, + for example. In order to configure a single cluster, specify a single JSON object with the cluster details. For multiple + clusters, specify objects in a comma-separated list with no trailing comma. The + cluster objects will be interpolated directly into a JSON array. + + + + ```json + { + "name": "local-service-cluster", + "load_assignment": { + "cluster_name": "local-service-cluster", + "endpoints": [ + { + "lb_endpoints": [ + { + "endpoint": { + "address": { + "socket_address": { + "address": "127.0.0.1", + "port_value": 32769 + } + } + } + } + ] + } + ] + } + } + ``` + + - `envoy_extra_static_listeners_json` - Similar to `envoy_extra_static_clusters_json` but appends one or more [Envoy listeners][pb-listener] to the array of [static @@ -480,23 +513,135 @@ definition](/docs/connect/registration/service-registration) or Can be used to setup limited access that bypasses Connect mTLS or authorization for health checks or metrics. + + + ```json + { + "name": "test_envoy_mtls_bypass_listener", + "address": { + "socket_address": { + "address": "0.0.0.0", + "port_value": 20201 + } + }, + "filter_chains": [ + { + "filters": [ + { + "name": "envoy.filters.network.http_connection_manager", + "typedConfig": { + "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager", + "http_filters": [ + { + "name": "envoy.filters.http.router" + } + ], + "route_config": { + "name": "self_admin_route", + "virtual_hosts": [ + { + "name": "self_admin", + "domains": [ + "*" + ], + "routes": [ + { + "match": { + "path": "/" + }, + "route": { + "cluster": "local-service-cluster" + } + } + ] + } + ] + }, + "stat_prefix": "envoy_mtls_bypass", + "tracing": { + "random_sampling": {} + } + } + } + ] + } + ] + } + ``` + + - `envoy_extra_stats_sinks_json` - Similar to `envoy_extra_static_clusters_json` but for [stats sinks](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-stats-sinks). These are appended to any sinks defined by use of the higher-level [`envoy_statsd_url`](#envoy_statsd_url) or [`envoy_dogstatsd_url`](#envoy_dogstatsd_url) config options. + + + ```json + { + "name": "envoy.stat_sinks.dog_statsd", + "typed_config": { + "@type": "type.googleapis.com/envoy.config.metrics.v3.DogStatsdSink", + "address": { + "socket_address": { + "protocol": "UDP", + "port_value": 8125, + "address": "172.31.20.6" + } + } + } + } + ``` + + - `envoy_stats_config_json` - The entire [stats config](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-stats-config). If provided this will override the higher-level [`envoy_stats_tags`](#envoy_stats_tags). It allows full control over dynamic tag replacements etc. + + + ```json + { + "stats_matcher": { + "reject_all": true + }, + "stats_tags": [ + { + "tag_name": "envoy.http_user_agent", + "regex": "^http(?=\\.).*?\\.user_agent\\.((.+?)\\.)\\w+?$" + } + ], + "use_all_default_tags": false + } + ``` + + - `envoy_tracing_json` - The entire [tracing config](https://www.envoyproxy.io/docs/envoy/v1.17.2/api-v3/config/bootstrap/v3/bootstrap.proto#envoy-v3-api-field-config-bootstrap-v3-bootstrap-tracing). Most tracing providers will also require adding static clusters to define the endpoints to send tracing data to. + + + ```json + { + "http": { + "name": "envoy.tracers.zipkin", + "typedConfig": { + "@type": "type.googleapis.com/envoy.config.trace.v3.ZipkinConfig", + "collector_cluster": "zipkin", + "collector_endpoint_version": "HTTP_JSON", + "collector_endpoint": "/api/v1/spans", + "shared_span_context": false + } + } + } + ``` + + ### Escape-Hatch Overrides Users may add the following configuration items to the [global `proxy-defaults` @@ -530,10 +675,135 @@ definition](/docs/connect/registration/service-registration) or prepended to the filters array to ensure that all inbound connections are authorized by Connect. Before Consul 1.9.0 `envoy.ext_authz` was inserted instead. + + + ```json + { + "@type": "type.googleapis.com/envoy.config.listener.v3.Listener", + "name": "public_listener", + "address": { + "socket_address": { + "address": "127.0.0.1", + "port_value": 21002 + } + }, + "filter_chains": [ + { + "filters": [ + { + "name": "envoy.filters.network.http_connection_manager", + "typed_config": { + "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager", + "stat_prefix": "ingress_http", + "http_filters": [ + { + "name": "envoy.filters.http.router" + } + ], + "route_config": { + "name": "local_route", + "virtual_hosts": [ + { + "name": "local_service", + "domains": ["*"], + "routes": [ + { + "match": { + "prefix": "/" + }, + "route": { + "cluster": "local-service-cluster", + } + } + ] + } + ] + } + } + } + ] + } + ], + "traffic_direction": "INBOUND" + } + ``` + + ```json + { + "@type": "type.googleapis.com/envoy.config.listener.v3.Listener", + "name": "public_listener", + "address": { + "socket_address": { + "address": "127.0.0.1", + "port_value": 21002 + } + }, + "filter_chains": [ + { + "filters": [ + { + "name": "envoy.filters.network.tcp_proxy", + "typed_config": { + "@type": "type.googleapis.com/envoy.extensions.filters.network.tcp_proxy.v3.TcpProxy", + "stat_prefix": "ingress_tcp", + "cluster": "local-service-cluster" + } + } + ] + } + ], + "traffic_direction": "INBOUND" + } + ``` + + + + - `envoy_local_cluster_json` - Specifies a complete [Envoy cluster][pb-cluster] to be delivered in place of the local application cluster. This allows customization of timeouts, rate limits, load balancing strategy etc. + + + ```json + { + "@type": "type.googleapis.com/envoy.config.cluster.v3.Cluster", + "name": "local_app", + "type": "STATIC", + "connect_timeout": "5s", + "circuit_breakers": { + "thresholds": [ + { + "priority": "DEFAULT", + "max_connections": 2048 + } + ] + }, + "load_assignment": { + "cluster_name": "local_app", + "endpoints": [ + { + "lb_endpoints": [ + { + "endpoint": { + "address": { + "socket_address": { + "address": "127.0.0.1", + "port_value": 8080 + } + } + } + } + ] + } + ] + } + } + ``` + + + + The following configuration items may be overridden directly in the `proxy.upstreams[].config` field of a [proxy service definition](/docs/connect/registration/service-registration) or @@ -556,11 +826,114 @@ warning. means there is no way to override Connect's mutual TLS for the public listener. + + + ```json + { + "@type": "type.googleapis.com/envoy.config.listener.v3.Listener", + "name": "example-service", + "address": { + "socket_address": { + "address": "0.0.0.0", + "port_value": 14000 + } + }, + "filter_chains": [ + { + "filters": [ + { + "name": "envoy.filters.network.http_connection_manager", + "typedConfig": { + "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager", + "access_log": [ + { + "name": "envoy.access_loggers.file", + "typedConfig": { + "@type": "type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog", + "path": "/var/log/envoy-access/example-service.log" + } + } + ], + "http_filters": [ + { + "name": "envoy.filters.http.router" + } + ], + "route_config": { + "name": "example-service", + "virtual_hosts": [ + { + "name": "example-service", + "domains": [ + "*" + ], + "routes": [ + { + "match": { + "prefix": "/" + }, + "route": { + "cluster": "example-service", + "timeout": "90s", + "retry_policy": { + "retry_on": "5xx,connect-failure", + "num_retries": 2, + "per_try_timeout": "60s" + } + } + } + ] + } + ] + }, + "stat_prefix": "example-service", + "tracing": { + "random_sampling": {} + } + } + } + ] + } + ], + "traffic_direction": "OUTBOUND" + } + ``` + + - `envoy_cluster_json` - Specifies a complete [Envoy cluster][pb-cluster] to be delivered in place of the discovered upstream cluster. This allows customization of timeouts, circuit breaking, rate limits, load balancing strategy etc. + + + ```json + { + "@type": "type.googleapis.com/envoy.config.cluster.v3.Cluster", + "name": "example-service", + "type": "EDS", + "eds_cluster_config": { + "eds_config": { + "ads": {} + } + }, + "connect_timeout": "90s", + "lb_policy": "ROUND_ROBIN", + "circuit_breakers": { + "thresholds": [ + { + "priority": "DEFAULT", + "max_connections": 1024, + "max_pending_requests": 1024, + "max_requests": 1024, + "max_retries": 3 + } + ] + } + } + ``` + + [protocol]: /docs/connect/config-entries/service-defaults#protocol [intentions]: /docs/connect/intentions [intentions]: /docs/connect/intentions