» Connect Configuration

There are many configuration options exposed for Connect. The only option that must be set is the "enabled" option on Consul Servers to enable Connect. All other configurations are optional and have reasonable defaults.

» Enable Connect on the Cluster

The first step to use Connect is to enable Connect for your Consul cluster. By default, Connect is disabled. Enabling Connect requires changing the configuration of only your Consul servers (not client agents). To enable Connect, add the following to a new or existing server configuration file. In HCL:

connect {
  enabled = true

This will enable Connect and configure your Consul cluster to use the built-in certificate authority for creating and managing certificates. You may also configure Consul to use an external certificate management system, such as Vault.

No agent-wide configuration is necessary for non-server agents. Services and proxies may always register with Connect settings, but they will fail to retrieve or verify any TLS certificates. This causes all Connect-based connection attempts to fail until Connect is enabled on the server agents.

» Built-In Proxy Options

This is a complete example of all the configuration options available for the built-in proxy. Note that only the service.connect.proxy.config map is being described here, the rest of the service definition is shown for context and is described elsewhere.

  "service": {
    "name": "web",
    "port": 8080,
    "connect": {
      "proxy": {
        "config": {
          "bind_address": "",
          "bind_port": 20000,
          "tcp_check_address": "",
          "disable_tcp_check": false,
          "local_service_address": "",
          "local_connect_timeout_ms": 1000,
          "handshake_timeout_ms": 10000,
          "upstreams": [
              "destination_type": "service",
              "destination_name": "redis",
              "destination_datacenter": "dc1",
              "local_bind_address": "",
              "local_bind_port": 1234,
              "connect_timeout_ms": 10000

» Configuration Key Reference

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 or [::] in which case this defaults to 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 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 - An array of upstream definitions for remote services that the proxied application needs to make outgoing connections to. Each definition has the following fields:

    • destination_name - [required] The name of the service or prepared query to route connect to.
    • local_bind_port - [required] The port to bind a local listener to for the application to make outbound connections to this upstream.
    • local_bind_address - The address to bind a local listener to for the application to make outbound connections to this upstream.
    • destination_type - Either service or upstream. The type of discovery query to use to find an instance to connect to. Defaults to service.
    • destination_datacenter - The datacenter to issue the discovery query too. Defaults to the local datacenter.
    • connect_timeout_ms - The number of milliseconds the proxy will wait to establish a connection to and complete TLS handshake with the remote application or proxy. Defaults to 10000 or 10 seconds.