github.com/KyaXTeam/consul@v1.4.5/website/source/docs/connect/proxies/envoy.md (about) 1 --- 2 layout: "docs" 3 page_title: "Connect - Envoy Integration" 4 sidebar_current: "docs-connect-proxies-envoy" 5 description: |- 6 Consul Connect has first-class support for configuring Envoy proxy. 7 --- 8 9 # Envoy Integration 10 11 Consul Connect has first class support for using 12 [Envoy](https://www.envoyproxy.io) as a proxy. Consul configures Envoy by 13 optionally exposing a gRPC service on the local agent that serves [Envoy's xDS 14 configuration 15 API](https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md). 16 17 Currently Consul only supports TCP proxying between services, however HTTP and 18 gRPC features are planned for the near future along with first class ways to 19 configure them in Consul. 20 21 As an interim solution, [custom Envoy configuration](#custom-configuration) can 22 be specified in [proxy service definition](/docs/connect/proxies.html) allowing 23 more powerful features of Envoy to be used. 24 25 ## Supported Versions 26 27 Consul's Envoy support was added in version 1.3.0. It has been tested against 28 Envoy 1.7.1 and 1.8.0. 29 30 31 ## Getting Started 32 33 To get started with Envoy and see a working example you can follow the [Using 34 Envoy with Connect](/docs/guides/connect-envoy.html) guide. 35 36 ## Limitations 37 38 The following list limitations of the Envoy integration as released in 1.3.0. 39 All of these are planned to be lifted in the near future. 40 41 * Default Envoy configuration only supports Layer 4 (TCP) proxying. More 42 [advanced listener configuration](#advanced-listener-configuration) is 43 possible but experimental and requires deep Envoy knowledge. First class 44 workflows for configuring Layer 7 features across the cluster are planned for 45 the near future. 46 * There is currently no way to override the configuration of upstream clusters 47 which makes it impossible to configure Envoy features like circuit breakers, 48 load balancing policy, custom protocol settings etc. This will be fixed in a 49 near-future release first with an "escape hatch" similar to the one for 50 listeners below, then later with first-class support. 51 * The configuration delivered to Envoy is suitable for a sidecar proxy 52 currently. Later we plan to support more flexibility to be able to configure 53 Envoy as an edge router or gateway and similar. 54 * There is currently no way to disable the public listener and have a "client 55 only" sidecar for services that don't expose Connect-enabled service but want 56 to consume others. This will be fixed in a near-future release. 57 * Once authorized, a persistent TCP connection will not be closed if the 58 intentions change to deny access. This is currently a limitation of how TCP 59 proxy and network authz filter work in Envoy. All new connections will be 60 denied though and destination services can limit exposure by closing inbound 61 connections periodically or by a rolling restart of the destination service 62 as an emergency measure. 63 64 ## Bootstrap Configuration 65 66 Envoy requires an initial bootstrap configuration that directs it to the local 67 agent for further configuration discovery. 68 69 To assist in generating this, Consul 1.3.0 adds a [`consul connect envoy` 70 command](/docs/commands/connect/envoy.html). The command can either output the 71 bootstrap configuration directly or can generate it and then `exec` the Envoy 72 binary as a convenience wrapper. 73 74 Some Envoy configuration options like metrics and tracing sinks can only be 75 specified via the bootstrap config currently and so a custom bootstrap must be 76 used. In order to work with Connect it's necessary to start with the following 77 basic template and add additional configuration as needed. 78 79 ```yaml 80 admin: 81 # access_log_path and address are required by Envoy, Consul doesn't care what 82 # they are set to though and never accesses the admin API. 83 node: 84 # cluter is required by Envoy but Consul doesn't use it 85 cluster: "<cluster_name" 86 # id must be the ID (not name if they differ) of the proxy service 87 # registration in Consul 88 id: "<proxy_service_id>" 89 static_resources: 90 clusters: 91 # local_agent is the "cluster" used to make further discovery requests for 92 # config and should point to the gRPC port of the local Consul agent instance. 93 - name: local_agent 94 connect_timeout: 1s 95 type: STATIC 96 # tls_context is needed if and only if Consul agent TLS is configured 97 tls_context: 98 common_tls_context: 99 validation_context: 100 trusted_ca: 101 filename: "<path to CA cert file Consul is using>" 102 http2_protocol_options: {} 103 hosts: 104 - socket_address: 105 address: "<agent's local IP address, usually 127.0.0.1>" 106 port_value: "<agent's grpc port, default 8502>" 107 dynamic_resources: 108 lds_config: 109 ads: {} 110 cds_config: 111 ads: {} 112 ads_config: 113 api_type: GRPC 114 grpc_services: 115 initial_metadata: 116 - key: "x-consul-token" 117 token: "<Consul ACL token with service:write on the target service>" 118 envoy_grpc: 119 cluster_name: local_agent 120 ``` 121 122 This configures a "cluster" pointing to the local Consul agent and sets that as 123 the target for discovering all types of dynamic resources. 124 125 ~> **Security Note**: The bootstrap configuration must contain the Consul ACL 126 token authorizing the proxy to identify as the target service. As such it should 127 be treated as a secret value and handled with care - an attacker with access to 128 one is able to obtain Connect TLS certificates for the target service and so 129 access anything that service is authorized to connect to. 130 131 ## Advanced Listener Configuration 132 133 Consul 1.3.0 includes initial Envoy support which includes automatic Layer 4 134 (TCP) proxying over mTLS, and authorization. Near future versions of Consul will 135 bring Layer 7 features like HTTP-path-based routing, retries, tracing and more. 136 137 -> **Advanced Topic!** This section covers an optional way of taking almost 138 complete control of Envoy's listener configuration which is provided as a way to 139 experiment with advanced integrations ahead of full layer 7 feature support. 140 While we don't plan to remove the ability to do this in the future, it should be 141 considered experimental and requires in-depth knowledge of Envoy's configuration 142 format. 143 144 For advanced users there is an "escape hatch" available in 1.3.0. The 145 `proxy.config` map in the [proxy service 146 definition](/docs/connect/proxies.html#proxy-service-definitions) may contain a 147 special key called `envoy_public_listener_json`. If this is set, it's value must 148 be a string containing the serialized proto3 JSON encoding of a complete [envoy 149 listener 150 config](https://www.envoyproxy.io/docs/envoy/v1.8.0/api-v2/api/v2/lds.proto). 151 Each upstream listener may also be customized in the same way by adding a 152 `envoy_listener_json` key to the `config` map of [the upstream 153 definition](/docs/connect/proxies.html#upstream-configuration-reference). 154 155 The JSON supplied may describe a protobuf `types.Any` message with `@type` set 156 to `type.googleapis.com/envoy.api.v2.Listener`, or it may be the direct encoding 157 of the listener with no `@type` field. 158 159 Once parsed, it is passed to Envoy in place of the listener config that Consul 160 would typically configure. The only modifications Consul will make to the config 161 provided are noted below. 162 163 #### Public Listener Configuration 164 165 For the `proxy.config.envoy_public_listener_json`, every `FilterChain` added to 166 the listener will have it's `TlsContext` overwritten with the Connect TLS 167 certificates. This means there is no way to override Connect TLS settings or the 168 requirement for all inbound clients to present valid Connect certificates. 169 170 Also, every `FilterChain` will have the `envoy.ext_authz` filter prepended to 171 the filters array to ensure that all incoming connections must be authorized 172 explicitly by the Consul agent based on their presented client certificate. 173 174 To work properly with Consul Connect, the public listener should bind to the 175 same address in the service definition so it is discoverable. It may also use 176 the special cluster name `local_app` to forward requests to a single local 177 instance if the proxy was configured [as a 178 sidecar](/docs/connect/proxies.html#sidecar-proxy-fields). 179 180 #### Example 181 182 The following example shows a public listener being configured with an http 183 connection manager. As specified this behaves exactly like the default TCP proxy 184 filter however it provides metrics on HTTP request volume and response codes. 185 186 If additional config outside of the listener is needed (for example the 187 top-level `tracing` configuration to send traces to a collecting service), those 188 currently need to be added to a custom bootstrap. You may generate the default 189 connect bootstrap with the [`consul connect envoy -bootstrap` 190 command](/docs/commands/connect/envoy.html) and then add the required additional 191 resources. 192 193 ```text 194 service { 195 kind = "connect-proxy" 196 name = "web-http-aware-proxy" 197 port = 8080 198 proxy { 199 destination_service_name = "web" 200 destination_service_id = "web" 201 config { 202 envoy_public_listener_json = <<EOL 203 { 204 "@type": "type.googleapis.com/envoy.api.v2.Listener", 205 "name": "public_listener:0.0.0.0:18080", 206 "address": { 207 "socketAddress": { 208 "address": "0.0.0.0", 209 "portValue": 8080 210 } 211 }, 212 "filterChains": [ 213 { 214 "filters": [ 215 { 216 "name": "envoy.http_connection_manager", 217 "config": { 218 "stat_prefix": "public_listener", 219 "route_config": { 220 "name": "local_route", 221 "virtual_hosts": [ 222 { 223 "name": "backend", 224 "domains": ["*"], 225 "routes": [ 226 { 227 "match": { 228 "prefix": "/" 229 }, 230 "route": { 231 "cluster": "local_app" 232 } 233 } 234 ] 235 } 236 ] 237 }, 238 "http_filters": [ 239 { 240 "name": "envoy.router", 241 "config": {} 242 } 243 ] 244 } 245 } 246 ] 247 } 248 ] 249 } 250 EOL 251 } 252 } 253 } 254 ``` 255 256 #### Upstream Listener Configuration 257 258 For the upstream listeners `proxy.upstreams[].config.envoy_listener_json`, no 259 modification is performed. The `Clusters` served via the xDS API all have the 260 correct client certificates and verification contexts configured so outbound 261 traffic should be authenticated. 262 263 Each upstream may separately choose to define a custom listener config. If 264 multiple upstreams define them care must be taken to ensure they all listen on 265 separate ports. 266 267 Currently there is no way to disable a listener for an upstream, or modify how 268 upstream service discovery clusters are delivered. Richer support for features 269 like this is planned for the near future. 270