Add proxy config reference and Complete TODOs in production guide

website/source/docs/connect/configuration.html.md

@@ -32,6 +32,11 @@ You may also configure Consul to use an external
 [certificate management system](/docs/connect/ca.html), such as
 [Vault](https://vaultproject.io).
 
+-> **Security note:** Enabling Connect is enough to try the feature but doesn't
+automatically ensure complete security. Please read the [Connect production
+guide](/docs/guides/connect-production.html) to understand the additional steps
+needed for a secure deployment.
+
 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
@@ -39,3 +44,97 @@ connection attempts to fail until Connect is enabled on the server agents.
 
 -> **Note:** Connect is enabled by default when running Consul in
 dev mode with `consul agent -dev`.
+
+## Built-In Proxy Options
+
+This is 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](/docs/connect/proxies.html#managed-proxies).
+
+```javascript
+{
+  "service": {
+    "name": "web",
+    "port": 8080,
+    "connect": {
+      "proxy": {
+        "config": {
+          "bind_address": "0.0.0.0",
+          "bind_port": 20000,
+          "local_service_address": "127.0.0.1:1234",
+          "local_connect_timeout_ms": 1000,
+          "handshake_timeout_ms": 10000,
+          "upstreams": [
+            {
+              "destination_type": "service",
+              "destination_name": "redis",
+              "destination_datacenter": "dc1",
+              "local_bind_address": "127.0.0.1",
+              "local_bind_port": 1234,
+              "connect_timeout_ms": 10000
+            },
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### Configuration Key Reference
+
+* <a name="bind_address"></a><a href="#bind_address">`bind_address`</a> -
+  The address the proxy will bind it's _public_ mTLS listener to. It
+  defaults to the same address the agent binds to.
+
+* <a name="bind_port"></a><a href="#bind_port">`bind_port`</a> - The
+  port the proxy will bind it's _public_ mTLS listener to. If not provided, the
+  agent will attempt to assing one from its [configured proxy port
+  range](/docs/agent/options.html#proxy_min_port) if available. By default the
+  range is [20000, 20255] and the port is selected at random from that range.
+
+* <a name="local_service_address"></a><a href="#local_service_address">`local_service_address`</a>
+  - 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.
+
+* <a name="local_connect_timeout_ms"></a><a href="#local_connect_timeout_ms">`local_connect_timeout_ms`</a>
+  - 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.
+
+* <a name="handshake_timeout_ms"></a><a href="#handshake_timeout_ms">`handshake_timeout_ms`</a>
+  - The number of milliseconds the proxy will wait for _incoming_ mTLS
+    connections to complete the TLS handshake. Defaults to `10000` or 10
+    seconds.
+
+* <a name="upstreams"></a><a href="#upstreams">`upstreams`</a>
+  - An array of upstream definitions for remote services that the proxied
+    application needs to make outgoing connections to. Each definition has the
+    following fields:
+    * <a name="destination_name"></a><a href="#destination_name">`destination_name`</a>
+      - [required] The name of the service or prepared query to route connect
+        to.
+    * <a name="local_bind_port"></a><a href="#local_bind_port">`local_bind_port`</a>
+      - [required] The port to bind a local listener to for the application to
+        make outbound connections to this upstream.
+    * <a name="local_bind_address"></a><a href="#local_bind_address">`local_bind_address`</a>
+      - The address to bind a local listener to for the application to make
+      outbound connections to this upstream.
+    * <a name="destination_type"></a><a href="#destination_type">`destination_type`</a>
+      - Either `service` or `upstream`. The type of discovery query to use to
+        find an instance to connect to. Defaults to `service`.
+    * <a name="destination_datacenter"></a><a href="#destination_datacenter">`destination_datacenter`</a>
+      - The datacenter to issue the discovery query too. Defaults to the local
+        datacenter.
+    * <a name="connect_timeout_ms"></a><a href="#connect_timeout_ms">`connect_timeout_ms`</a>
+      - 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.
+

website/source/docs/connect/proxies.html.md

@@ -118,6 +118,9 @@ static port will be able to masquerade as the source service ("web" in the
 example above). You must either trust any loopback access on that port or
 use namespacing techniques provided by your operating system.
 
+For full details of the configurable options available see the [built-in proxy
+configuration reference](/docs/connect/configuration.html#built-in-proxy-options).
+
 ### Prepared Query Upstreams
 
 The upstream destination may also be a
@@ -157,6 +160,9 @@ only be used to discover services within a single datacenter. See
 [Multi-Datacenter Connect](/docs/connect/index.html#multi-datacenter) for
 more information.
 
+For full details of the configurable options available see the [built-in proxy
+configuration reference](/docs/connect/configuration.html#built-in-proxy-options).
+
 ### Dynamic Upstreams
 
 If an application requires dynamic dependencies that are only available

website/source/docs/guides/connect-production.md

@@ -134,7 +134,7 @@ bootstrap a new CA and generate it's own private key which is written to the
 Raft state.
 
 Alternatively, an external private key can be provided via the [CA
-configuration](#TODO).
+configuration](/docs/connect/ca.html#specifying-a-private-key-and-root-certificate).
 
 ### External CAs
 
@@ -143,11 +143,10 @@ integrated. We will expand the external CA systems that are supported in the
 future and will allow seamless online migration to a different CA or
 bootstrapping with an external CA.
 
-For production workloads we recommend using Vault or another external CA once
+For production workloads we recommend using [Vault or another external
+CA](/docs/connect/ca.html#external-ca-certificate-authority-providers) once
 available such that the root key is not stored within Consul state at all.
 
-TODO: link to vault config docs?
-
 ## Setup Host Firewall
 
 In order to enable inbound connections to connect proxies, you may need to
@@ -166,11 +165,12 @@ that range are both free to use (no other processes listening on them) and are
 exposed in the firewall to accept connections from other service hosts.
 
 Alternatively, managed proxies can have their public ports specified as part of
-the [proxy configuration](#TODO) in the service registration. It is possible to use
+the [proxy
-this exclusively and prevent automated port selection by [configuring
+configuration](/docs/connect/configuration.html#local_bind_port) in the
-`proxy_min_port` and
+service definition. It is possible to use this exclusively and prevent
-`proxy_max_port`](/docs/agent/options.html#ports)
+automated port selection by [configuring `proxy_min_port` and
-to both be `0`, forcing any managed proxies to have an explicit port configured.
+`proxy_max_port`](/docs/agent/options.html#ports) to both be `0`, forcing any
+managed proxies to have an explicit port configured.
 
 It then becomes the same problem as opening ports necessary for any other
 application and might be managed by configuration management or a scheduler.