github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

docs: Add example Envoy escape hatch configs (#12764) 

Add example escape hatch configurations for all supported override
types.
pull/12915/head
Blake Covarrubias 3 years ago committed by GitHub
parent
b2a005342b
commit
54119f3225
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 377 additions and 4 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 381
      website/content/docs/connect/proxies/envoy.mdx

381
website/content/docs/connect/proxies/envoy.mdx
Unescape View File

@ -386,6 +386,8 @@ field set to the appropriate type (for example
For example, given a tracing config:
<CodeBlockConfig heading="Example envoy_tracing_json configuration">
```json
{
"http": {
@ -401,6 +403,8 @@ For example, given a tracing config:
}
```
</CodeBlockConfig>
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.
<CodeBlockConfig heading="Example envoy_extra_static_clusters_json">
```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
}
}
}
}
]
}
]
}
}
```
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Example envoy_extra_static_listeners_json">
```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": {}
}
}
}
]
}
]
}
```
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Example envoy_extra_stats_sinks_json">
```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"
}
}
}
}
```
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Example envoy_stats_config_json">
```json
{
"stats_matcher": {
"reject_all": true
},
"stats_tags": [
{
"tag_name": "envoy.http_user_agent",
"regex": "^http(?=\\.).*?\\.user_agent\\.((.+?)\\.)\\w+?$"
}
],
"use_all_default_tags": false
}
```
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Example envoy_tracing_json">
```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
}
}
}
```
</CodeBlockConfig>
### 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.
<CodeTabs heading="Example envoy_public_listener_json" tabs={[ "HTTP", "TCP" ]}>
```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"
}
```
</CodeTabs>
- `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.
<CodeBlockConfig heading="Example envoy_local_cluster_json">
```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
}
}
}
}
]
}
]
}
}
```
</CodeBlockConfig>
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.
<CodeTabs heading="Example upstream envoy_listener_json">
```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"
}
```
</CodeTabs>
- `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.
<CodeTabs heading="Example upstream envoy_cluster_json">
```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
}
]
}
}
```
</CodeTabs>
[protocol]: /docs/connect/config-entries/service-defaults#protocol
[intentions]: /docs/connect/intentions
[intentions]: /docs/connect/intentions

Write Preview
Loading…
Cancel
Save