github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/configuration/tls.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: tls Stanza - Agent Configuration
     4  description: |-
     5    The "tls" stanza configures Nomad's TLS communication via HTTP and RPC to
     6    enforce secure cluster communication between servers and clients.
     7  ---
     8  
     9  # `tls` Stanza
    10  
    11  <Placement groups={['tls']} />
    12  
    13  The `tls` stanza configures Nomad's TLS communication via HTTP and RPC to
    14  enforce secure cluster communication between servers, clients, and between.
    15  
    16  ```hcl
    17  tls {
    18    http = true
    19    rpc  = true
    20  }
    21  ```
    22  
    23  ~> Incorrect configuration of the TLS configuration can result in failure to
    24  start the Nomad agent.
    25  
    26  This section of the documentation only covers the configuration options for
    27  `tls` stanza. To understand how to setup the certificates themselves, please see
    28  the [Enable TLS Encryption for Nomad Tutorial](https://learn.hashicorp.com/tutorials/nomad/security-enable-tls).
    29  
    30  ## `tls` Parameters
    31  
    32  - `ca_file` `(string: "")` - Specifies the path to the CA certificate to use for
    33    Nomad's TLS communication.
    34  
    35  - `cert_file` `(string: "")` - Specifies the path to the certificate file used
    36    for Nomad's TLS communication.
    37  
    38  - `key_file` `(string: "")` - Specifies the path to the key file to use for
    39    Nomad's TLS communication.
    40  
    41  - `http` `(bool: false)` - Specifies if TLS should be enabled on the HTTP
    42    endpoints on the Nomad agent, including the API.
    43  
    44  - `rpc` `(bool: false)` - Specifies if TLS should be enabled on the RPC
    45    endpoints and [Raft][raft] traffic between the Nomad servers. Enabling this on
    46    a Nomad client makes the client use TLS for making RPC requests to the Nomad
    47    servers.
    48  
    49  - `rpc_upgrade_mode` `(bool: false)` - This option should be used only when the
    50    cluster is being upgraded to TLS, and removed after the migration is
    51    complete. This allows the agent to accept both TLS and plaintext traffic.
    52  
    53  - `tls_cipher_suites` `string: "")` - Specifies the TLS cipher suites that will
    54    be used by the agent as a comma-separated string. Known insecure ciphers are
    55    disabled (3DES and RC4). By default, an agent is configured to use
    56    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
    57    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
    58    TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,
    59    TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
    60    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
    61    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
    62    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
    63    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
    64    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 and
    65    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256.
    66  
    67  - `tls_min_version` `(string: "tls12")`- Specifies the minimum supported version
    68    of TLS. Accepted values are "tls10", "tls11", "tls12".
    69  
    70  - `tls_prefer_server_cipher_suites` `(bool: false)` - Specifies whether
    71    TLS connections should prefer the server's ciphersuites over the client's.
    72  
    73  - `verify_https_client` `(bool: false)` - Specifies agents should require
    74    client certificates for all incoming HTTPS requests. The client certificates
    75    must be signed by the same CA as Nomad.
    76  
    77  - `verify_server_hostname` `(bool: false)` - Specifies if outgoing TLS
    78    connections should verify the server's hostname.
    79  
    80  ## `tls` Examples
    81  
    82  The following examples only show the `tls` stanzas. Remember that the
    83  `tls` stanza is only valid in the placements listed above.
    84  
    85  ### Enabling TLS
    86  
    87  This example shows enabling TLS configuration. This enables TLS communication
    88  between all servers and clients using the default system CA bundle and
    89  certificates.
    90  
    91  ```hcl
    92  tls {
    93    http = true
    94    rpc  = true
    95  
    96    ca_file   = "/etc/certs/ca.crt"
    97    cert_file = "/etc/certs/nomad.crt"
    98    key_file  = "/etc/certs/nomad.key"
    99  }
   100  ```
   101  
   102  ### `tls` Configuration Reloads
   103  
   104  Nomad supports dynamically reloading both client and server TLS
   105  configuration. To reload an agent's TLS configuration, first update the TLS
   106  block in the agent's configuration file and then send the Nomad agent a
   107  `SIGHUP` signal. Note that this will only reload a subset of the configuration
   108  file, including the TLS configuration.
   109  
   110  The agent reloads all its network connections when there are changes to its
   111  TLS configuration during a config reload via `SIGHUP`. Any new connections
   112  established will use the updated configuration, and any outstanding old
   113  connections will be closed. This process works when upgrading to TLS,
   114  downgrading from it, as well as rolling certificates.
   115  
   116  [raft]: https://github.com/hashicorp/serf 'Serf by HashiCorp'