tls Block

The tls block configures Nomad's TLS communication via HTTP and RPC to enforce secure cluster communication between servers, clients, and between.

tls {
  http = true
  rpc  = true
}

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.

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 mTLS should be enabled on the HTTP endpoints on the Nomad agent, including the API.

• rpc (bool: false) - Toggle the option to enable mTLS on the RPC endpoints and 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.

• 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 blocks. Remember that the tls block 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.

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.