mirror of
https://github.com/status-im/consul.git
synced 2025-01-11 06:16:08 +00:00
Add proxy config reference and Complete TODOs in production guide
This commit is contained in:
Paul Banks
Jack Pearkes
parent
959f0c612c
commit
f0059665bb
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
this exclusively and prevent automated port selection by [configuring
|
||||
`proxy_min_port` and
|
||||
`proxy_max_port`](/docs/agent/options.html#ports)
|
||||
to both be `0`, forcing any managed proxies to have an explicit port configured.
|
||||
the [proxy
|
||||
configuration](/docs/connect/configuration.html#local_bind_port) in the
|
||||
service definition. It is possible to use this exclusively and prevent
|
||||
automated port selection by [configuring `proxy_min_port` and
|
||||
`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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user