diff --git a/website/source/guides/tls.html.md b/website/source/guides/tls.html.md index ba325e735..1c71c38db 100644 --- a/website/source/guides/tls.html.md +++ b/website/source/guides/tls.html.md @@ -3,7 +3,9 @@ layout: "guides" page_title: "Securing Nomad with TLS" sidebar_current: "guides-tls" description: |- - Securing Nomad's cluster communication with TLS is XXX TODO XXX + Securing Nomad's cluster communication is not only important for security but + can even ease operations by preventing mistakes and misconfigurations. Nomad + optionally uses mutual TLS (mTLS) for all HTTP and RPC communication. --- # Securing Nomad with TLS @@ -32,8 +34,6 @@ configuration. management and rotation is a complex subject not covered by this guide. [Vault][] is the suggested solution for key generation and management. -XXX TODO XXX - serf encryption key - ## Creating Certificates The first step to configuring TLS for Nomad is generating certificates. In @@ -310,9 +310,60 @@ vagrant@nomad:~$ nomad run example.nomad ==> Evaluation "e9970e1d" finished with status "complete" ``` +## Server Gossip + +We haven't quite completely secured Nomad's communications: Nomad server's +gossip protocol uses a shared key instead of TLS for encryption. This +encryption key must be added to every server's configuration using the +[`encrypt`](/docs/agent/configuration/server.html#encrypt) parameter. + +As a convenience the Nomad CLI includes a `keygen` command for generating a new +secure gossip encryption key: + +```text +$ nomad keygen +cg8StVXbQJ0gPvMd9o7yrg== +``` + +Put the generated key into each server's configuration file: + +```hcl +server { + enabled = true + + # Self-elect, should be 3 or 5 for production + bootstrap_expect = 1 + + # Encrypt gossip communication + encrypt = "cg8StVXbQJ0gPvMd9o7yrg==" +} +``` + ## Switching an existing cluster to TLS -XXX TODO XXX +Since Nomad does *not* use different ports for TLS and non-TLS communication, +the use of TLS should be consistent across the cluster. Switching an existing +cluster to use TLS everywhere is similar to upgrading between versions of +Nomad. + +First make sure all of your nodes are ready to be switched: + +* Add the appropriate key and certificates to all nodes. + * Ensure the private key file is only readable by the Nomad user. +* Add the environment variables to all nodes where the CLI is used. +* Add the appropriate `tls` block to the configuration file on all nodes. +* Generate a gossip key and add it the Nomad server configuration. + +At this point a rolling restart of the cluster will enable TLS everywhere. + +1. Restart servers, one at a time +2. Restart clients, one or more at a time + +~> As soon as a quorum of servers are TLS-enabled, clients will not be able to + communicate with them until they are restarted. + +Jobs running in the cluster will *not* be affected and will continue running +throughout the switch. [guide-server]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/server.hcl [guide-cluster]: https://www.nomadproject.io/intro/getting-started/cluster.html