github.com/outbrain/consul@v1.4.5/website/source/docs/connect/configuration.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Connect - Configuration"
     4  sidebar_current: "docs-connect-config"
     5  description: |-
     6    A Connect-aware proxy enables unmodified applications to use Connect. A per-service proxy sidecar transparently handles inbound and outbound service connections, automatically wrapping and verifying TLS connections.
     7  ---
     8  
     9  # Connect Configuration
    10  
    11  There are many configuration options exposed for Connect. The only option
    12  that must be set is the "enabled" option on Consul Servers to enable Connect.
    13  All other configurations are optional and have reasonable defaults.
    14  
    15  ## Enable Connect on the Cluster
    16  
    17  The first step to use Connect is to enable Connect for your Consul
    18  cluster. By default, Connect is disabled. Enabling Connect requires changing
    19  the configuration of only your Consul _servers_ (not client agents). To enable
    20  Connect, add the following to a new or existing
    21  [server configuration file](/docs/agent/options.html). In HCL:
    22  
    23  ```hcl
    24  connect {
    25    enabled = true
    26  }
    27  ```
    28  
    29  This will enable Connect and configure your Consul cluster to use the
    30  built-in certificate authority for creating and managing certificates.
    31  You may also configure Consul to use an external
    32  [certificate management system](/docs/connect/ca.html), such as
    33  [Vault](https://vaultproject.io).
    34  
    35  No agent-wide configuration is necessary for non-server agents. Services
    36  and proxies may always register with Connect settings, but they will fail to
    37  retrieve or verify any TLS certificates. This causes all Connect-based
    38  connection attempts to fail until Connect is enabled on the server agents.
    39  
    40  -> **Note:** Connect is enabled by default when running Consul in
    41  dev mode with `consul agent -dev`.
    42  
    43  ~> **Security note:** Enabling Connect is enough to try the feature but doesn't
    44  automatically ensure complete security. Please read the [Connect production
    45  guide](/docs/guides/connect-production.html) to understand the additional steps
    46  needed for a secure deployment.
    47  
    48  ## Built-In Proxy Options
    49  
    50  This is a complete example of all the configuration options available for the
    51  built-in proxy. Note that only the `service.connect.proxy.config` and
    52  `service.connect.proxy.upsteams[].config` maps are being described here, the
    53  rest of the service definition is shown for context but is [described
    54  elsewhere](/docs/connect/proxies.html#managed-proxies).
    55  
    56  ```javascript
    57  {
    58    "service": {
    59      ...
    60      "connect": {
    61        "proxy": {
    62          "config": {
    63            "bind_address": "0.0.0.0",
    64            "bind_port": 20000,
    65            "tcp_check_address": "192.168.0.1",
    66            "disable_tcp_check": false,
    67            "local_service_address": "127.0.0.1:1234",
    68            "local_connect_timeout_ms": 1000,
    69            "handshake_timeout_ms": 10000,
    70            "upstreams": [...]
    71          },
    72          "upstreams": [
    73            {
    74              ...
    75              "config": {
    76                "connect_timeout_ms": 1000
    77              }
    78            }
    79          ]
    80        }
    81      }
    82    }
    83  }
    84  ```
    85  
    86  #### Proxy Config Key Reference
    87  
    88  All fields are optional with a sane default.
    89  
    90  * <a name="bind_address"></a><a href="#bind_address">`bind_address`</a> -
    91    The address the proxy will bind it's _public_ mTLS listener to. It
    92    defaults to the same address the agent binds to.
    93  
    94  * <a name="bind_port"></a><a href="#bind_port">`bind_port`</a> - The
    95    port the proxy will bind it's _public_ mTLS listener to. If not provided, the
    96    agent will attempt to assign one from its [configured proxy port
    97    range](/docs/agent/options.html#proxy_min_port) if available. By default the
    98    range is [20000, 20255] and the port is selected at random from that range.
    99  
   100  * <a name="tcp_check_address"></a><a
   101    href="#tcp_check_address">`tcp_check_address`</a> - The address the agent will
   102    run a [TCP health check](/docs/agent/checks.html) against. By default this is
   103    the same as the proxy's [bind address](#bind_address) except if the
   104    bind_address is `0.0.0.0` or `[::]` in which case this defaults to `127.0.0.1`
   105    and assumes the agent can dial the proxy over loopback. For more complex
   106    configurations where agent and proxy communicate over a bridge for example,
   107    this configuration can be used to specify a different _address_ (but not port)
   108    for the agent to use for health checks if it can't talk to the proxy over
   109    localhost or it's publicly advertised port. The check always uses the same
   110    port that the proxy is bound to.
   111  
   112  * <a name="disable_tcp_check"></a><a
   113    href="#disable_tcp_check">`disable_tcp_check`</a> - If true, this disables a
   114    TCP check being setup for the proxy. Default is false.
   115  
   116  * <a name="local_service_address"></a><a href="#local_service_address">`local_service_address`</a> - The
   117    `[address]:port` that the proxy should use to connect to the local application
   118    instance. By default it assumes `127.0.0.1` as the address and takes the port
   119    from the service definition's `port` field. Note that allowing the application
   120    to listen on any non-loopback address may expose it externally and bypass
   121    Connect's access enforcement. It may be useful though to allow non-standard
   122    loopback addresses or where an alternative known-private IP is available for
   123    example when using internal networking between containers.
   124  
   125  * <a name="local_connect_timeout_ms"></a><a href="#local_connect_timeout_ms">`local_connect_timeout_ms`</a> - The number
   126    of milliseconds the proxy will wait to establish a connection to the _local
   127    application_ before giving up. Defaults to `1000` or 1 second.
   128  
   129  * <a name="handshake_timeout_ms"></a><a href="#handshake_timeout_ms">`handshake_timeout_ms`</a> - The
   130    number of milliseconds the proxy will wait for _incoming_ mTLS connections to 
   131    complete the TLS handshake. Defaults to `10000` or 10 seconds.
   132  
   133  * <a name="upstreams"></a><a href="#upstreams">`upstreams`</a> - **Deprecated**
   134    Upstreams are now specified in the `connect.proxy` definition. Upstreams
   135    specified in the opaque config map here will continue to work for
   136    compatibility but it's strongly recommended that you move to using the higher
   137    level [upstream
   138    configuration](/docs/connect/proxies.html#upstream-configuration).
   139  
   140  #### Proxy Upstream Config Key Reference
   141  
   142  All fields are optional with a sane default.
   143  
   144  * <a name="connect_timeout_ms"></a><a
   145    href="#connect_timeout_ms">`connect_timeout_ms`</a> - The number of
   146    milliseconds the proxy will wait to establish a TLS connection to the
   147    discovered upstream instance before giving up. Defaults to `10000` or 10
   148    seconds.