mirror of
https://github.com/kemko/nomad.git
synced 2026-01-04 17:35:43 +03:00
1e51379e56
Some of our documentation on `tls` configuration could be more clear as to whether we're referring to mTLS or TLS. Also, when ACLs are enabled it's fine to have `verify_https_client=false` (the default). Make it clear that this is an acceptably secure configuration and that it's in fact recommended in order to avoid pain of distributing client certs to user browsers.
130 lines
5.1 KiB
Plaintext
130 lines
5.1 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: tls Block - Agent Configuration
|
|
description: |-
|
|
The "tls" block configures Nomad's TLS communication via HTTP and RPC to
|
|
enforce secure cluster communication between servers and clients.
|
|
---
|
|
|
|
# `tls` Block
|
|
|
|
<Placement groups={['tls']} />
|
|
|
|
The `tls` block configures Nomad's TLS communication via HTTP and RPC to enforce
|
|
secure cluster communication between servers, clients, and between. Note that in
|
|
most cases, this is mutual TLS (mTLS) where both ends of the connection
|
|
authenticate each other. The Nomad documentation will typically use "TLS" to
|
|
refer to this communication except when it is potentially ambiguous between TLS
|
|
and mTLS.
|
|
|
|
```hcl
|
|
tls {
|
|
http = true
|
|
rpc = true
|
|
}
|
|
```
|
|
|
|
~> Incorrect configuration of the TLS configuration can result in failure to
|
|
start the Nomad agent.
|
|
|
|
This section of the documentation only covers the configuration options for
|
|
`tls` block. To understand how to setup the certificates themselves, please see
|
|
the [Enable TLS Encryption for Nomad Tutorial](/nomad/tutorials/transport-security/security-enable-tls).
|
|
|
|
## `tls` Parameters
|
|
|
|
- `ca_file` `(string: "")` - Specifies the path to the CA certificate to use for
|
|
Nomad's TLS communication.
|
|
|
|
- `cert_file` `(string: "")` - Specifies the path to the certificate file used
|
|
for Nomad's TLS communication.
|
|
|
|
- `key_file` `(string: "")` - Specifies the path to the key file to use for
|
|
Nomad's TLS communication.
|
|
|
|
- `http` `(bool: false)` - Specifies if TLS should be enabled on the HTTP
|
|
endpoints on the Nomad agent, including the API. By default this is non-mutual
|
|
TLS. You can upgrade this to mTLS by setting
|
|
[`verify_https_client=true`](#verify_https_client), but this can complicate
|
|
using the Nomad UI by requiring mTLS in your browser or running a proxy in
|
|
front of the Nomad UI.
|
|
|
|
- `rpc` `(bool: false)` - Toggle the option to enable mTLS on the RPC endpoints
|
|
and [Raft][raft] traffic. When this setting is activated, it establishes
|
|
protection both between Nomad servers and from the clients back to the
|
|
servers, ensuring mutual authentication. Setting `rpc=true` is required for
|
|
secure operation of Nomad.
|
|
|
|
- `rpc_upgrade_mode` `(bool: false)` - This option should be used only when the
|
|
cluster is being upgraded to TLS, and removed after the migration is
|
|
complete. This allows the agent to accept both TLS and plaintext traffic.
|
|
|
|
- `tls_cipher_suites` `string: "")` - Specifies the TLS cipher suites that will
|
|
be used by the agent as a comma-separated string. Known insecure ciphers are
|
|
disabled (3DES and RC4). By default, an agent is configured to use
|
|
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
|
|
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
|
|
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
|
|
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
|
|
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
|
|
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
|
|
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
|
|
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
|
|
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 and
|
|
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256.
|
|
|
|
- `tls_min_version` `(string: "tls12")`- Specifies the minimum supported version
|
|
of TLS. Accepted values are "tls10", "tls11", "tls12".
|
|
|
|
- `tls_prefer_server_cipher_suites` `(bool: false)` - Specifies whether
|
|
TLS connections should prefer the server's ciphersuites over the client's.
|
|
|
|
- `verify_https_client` `(bool: false)` - Specifies agents should require client
|
|
certificates for all incoming HTTPS requests, effectively upgrading
|
|
[`tls.http=true`](#http) to mTLS. The client certificates must be signed by
|
|
the same CA as Nomad. By default, `verify_https_client` is set to `false`,
|
|
which is safe so long as ACLs are enabled. This is recommended if you are
|
|
using the Nomad web UI to avoid the difficulty of distributing client certs to
|
|
browsers.
|
|
|
|
- `verify_server_hostname` `(bool: false)` - Specifies if outgoing TLS
|
|
connections should verify the server's hostname.
|
|
|
|
## `tls` Examples
|
|
|
|
The following examples only show the `tls` blocks. Remember that the
|
|
`tls` block is only valid in the placements listed above.
|
|
|
|
### Enabling TLS
|
|
|
|
This example shows enabling TLS configuration. This enables mTLS communication
|
|
between all servers and clients using the default system CA bundle and
|
|
certificates.
|
|
|
|
```hcl
|
|
tls {
|
|
http = true
|
|
rpc = true
|
|
|
|
ca_file = "/etc/certs/ca.crt"
|
|
cert_file = "/etc/certs/nomad.crt"
|
|
key_file = "/etc/certs/nomad.key"
|
|
}
|
|
```
|
|
|
|
### `tls` Configuration Reloads
|
|
|
|
Nomad supports dynamically reloading both client and server TLS
|
|
configuration. To reload an agent's TLS configuration, first update the TLS
|
|
block in the agent's configuration file and then send the Nomad agent a `SIGHUP`
|
|
signal. Note that this will only reload a subset of the configuration file,
|
|
including the TLS configuration.
|
|
|
|
The agent reloads all its network connections when there are changes to its
|
|
TLS configuration during a config reload via `SIGHUP`. Any new connections
|
|
established will use the updated configuration, and any outstanding old
|
|
connections will be closed. This process works when upgrading to TLS,
|
|
downgrading from it, as well as rolling certificates.
|
|
|
|
[raft]: https://github.com/hashicorp/serf 'Serf by HashiCorp'
|