Built-In Proxy Options

Note: The built-in proxy is not supported for production deployments. It does not support many of the Connect service mesh features, and is not under active development. The Envoy proxy should be used for production deployments.

Consul comes with a built-in L4 proxy for testing and development with Consul Connect service mesh.

Proxy Config Key Reference

Below is a complete example of all the configuration options available for the built-in proxy.

  1. {
  2.   "service": {
  3.     ...
  4.     "connect": {
  5.       "proxy": {
  6.         "config": {
  7.           "bind_address": "0.0.0.0",
  8.           "bind_port": 20000,
  9.           "local_service_address": "127.0.0.1:1234",
  10.           "local_connect_timeout_ms": 1000,
  11.           "handshake_timeout_ms": 10000,
  12.           "upstreams": [...]
  13.         },
  14.         "upstreams": [
  15.           {
  16.             ...
  17.             "config": {
  18.               "connect_timeout_ms": 1000
  19.             }
  20.           }
  21.         ]
  22.       }
  23.     }
  24.   }
  25. }
  1. {
  2.   "service": {
  3.     ...
  4.     "connect": {
  5.       "proxy": {
  6.         "config": {
  7.           "bind_address": "0.0.0.0",
  8.           "bind_port": 20000,
  9.           "local_service_address": "127.0.0.1:1234",
  10.           "local_connect_timeout_ms": 1000,
  11.           "handshake_timeout_ms": 10000,
  12.           "upstreams": [...]
  13.         },
  14.         "upstreams": [
  15.           {
  16.             ...
  17.             "config": {
  18.               "connect_timeout_ms": 1000
  19.             }
  20.           }
  21.         ]
  22.       }
  23.     }
  24.   }
  25. }

All fields are optional with a reasonable default.

  • bind_address - The address the proxy will bind its public mTLS listener to. It defaults to the same address the agent binds to.

  • bind_port - The port the proxy will bind its public mTLS listener to. If not provided, the agent will assign a random port from its configured proxy port range specified by sidecar_min_port and sidecar_max_port.

  • local_service_address- The [address]:port that the proxy should use to connect to the local application instance. By default it assumes 127.0.0.1 as the address and takes the port from the service definition’s port field. Note that allowing the application to listen on any non-loopback address may expose it externally and bypass Connect’s access enforcement. It may be useful though to allow non-standard loopback addresses or where an alternative known-private IP is available for example when using internal networking between containers.

  • local_connect_timeout_ms - The number of milliseconds the proxy will wait to establish a connection to the local application before giving up. Defaults to 1000 or 1 second.

  • handshake_timeout_ms - The number of milliseconds the proxy will wait for incoming mTLS connections to complete the TLS handshake. Defaults to 10000 or 10 seconds.

  • upstreams- Deprecated Upstreams are now specified in the connect.proxy definition. Upstreams specified in the opaque config map here will continue to work for compatibility but it’s strongly recommended that you move to using the higher level upstream configuration.

Proxy Upstream Config Key Reference

All fields are optional with a reasonable default.

  • connect_timeout_ms - The number of milliseconds the proxy will wait to establish a TLS connection to the discovered upstream instance before giving up. Defaults to 10000 or 10 seconds.