117 lines
4.2 KiB
Plaintext
117 lines
4.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: tls Stanza - Agent Configuration
|
|
description: |-
|
|
The "tls" stanza configures Nomad's TLS communication via HTTP and RPC to
|
|
enforce secure cluster communication between servers, clients, and between.
|
|
---
|
|
|
|
# `tls` Stanza
|
|
|
|
<Placement groups={['tls']} />
|
|
|
|
The `tls` stanza configures Nomad's TLS communication via HTTP and RPC to
|
|
enforce secure cluster communication between servers, clients, and between.
|
|
|
|
```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` stanza. To understand how to setup the certificates themselves, please see
|
|
the [Enable TLS Encryption for Nomad Tutorial](https://learn.hashicorp.com/tutorials/nomad/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.
|
|
|
|
- `rpc` `(bool: false)` - Specifies if TLS should be enabled on the RPC
|
|
endpoints and [Raft][raft] traffic between the Nomad servers. Enabling this on
|
|
a Nomad client makes the client use TLS for making RPC requests to the Nomad
|
|
servers.
|
|
|
|
- `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. The client certificates
|
|
must be signed by the same CA as Nomad.
|
|
|
|
- `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` stanzas. Remember that the
|
|
`tls` stanza is only valid in the placements listed above.
|
|
|
|
### Enabling TLS
|
|
|
|
This example shows enabling TLS configuration. This enables TLS 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'
|