Built-In Proxy Options

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

Note: Envoy should be used for production deployments, or when layer 7 traffic management features are needed.

Getting Started

To get started with the built-in proxy and see a working example you can follow the Getting Started tutorial.

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.           "tcp_check_address": "192.168.0.1",
  10.           "disable_tcp_check": false,
  11.           "local_service_address": "127.0.0.1:1234",
  12.           "local_connect_timeout_ms": 1000,
  13.           "handshake_timeout_ms": 10000,
  14.           "upstreams": [...]
  15.         },
  16.         "upstreams": [
  17.           {
  18.             ...
  19.             "config": {
  20.               "connect_timeout_ms": 1000
  21.             }
  22.           }
  23.         ]
  24.       }
  25.     }
  26.   }
  27. }

All fields are optional with a sane default.

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

  • bind_port - The port the proxy will bind it’s public mTLS listener to. If not provided, the agent will attempt to assign one from its configured proxy port range if available. By default the range is [20000, 20255] and the port is selected at random from that range.

  • tcp_check_address - The address the agent will run a TCP health check against. By default this is the same as the proxy’s bind address except if the bind address is 0.0.0.0 or [::] in which case this defaults to 127.0.0.1 and assumes the agent can dial the proxy over loopback. For more complex configurations where agent and proxy communicate over a bridge for example, this configuration can be used to specify a different address (but not port) for the agent to use for health checks if it can’t talk to the proxy over localhost or it’s publicly advertised port. The check always uses the same port that the proxy is bound to.

  • disable_tcp_check - If true, this disables a TCP check being setup for the proxy. Default is false.

  • 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 sane 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.