Merge pull request #2923 from hashicorp/d-tls-guide

TLS Guide

demo/vagrant/Vagrantfile

@@ -67,6 +67,13 @@ EOF
 sudo systemctl enable consul.service
 sudo systemctl start consul
 
+for bin in cfssl cfssl-certinfo cfssljson
+do
+	echo "Installing $bin..."
+	curl -sSL https://pkg.cfssl.org/R1.2/${bin}_linux-amd64 > /tmp/${bin}
+	sudo install /tmp/${bin} /usr/local/bin/${bin}
+done
+
 SCRIPT
 
 Vagrant.configure(2) do |config|

demo/vagrant/cfssl.json

@@ -0,0 +1,13 @@
+{
+    "signing": {
+        "default": {
+            "expiry": "87600h",
+            "usages": [
+                "signing",
+                "key encipherment",
+                "server auth",
+                "client auth"
+            ]
+        }
+    }
+}

demo/vagrant/client1.hcl

@@ -6,15 +6,15 @@ data_dir = "/tmp/client1"
 
 # Enable the client
 client {
-    enabled = true
+  enabled = true
 
-    # For demo assume we are talking to server1. For production,
-    # this should be like "nomad.service.consul:4647" and a system
-    # like Consul used for service discovery.
-    servers = ["127.0.0.1:4647"]
+  # For demo assume we are talking to server1. For production,
+  # this should be like "nomad.service.consul:4647" and a system
+  # like Consul used for service discovery.
+  servers = ["127.0.0.1:4647"]
 }
 
 # Modify our port to avoid a collision with server1
 ports {
-    http = 5656
+  http = 5656
 }

demo/vagrant/client2.hcl

@@ -6,15 +6,15 @@ data_dir = "/tmp/client2"
 
 # Enable the client
 client {
-    enabled = true
+  enabled = true
 
-    # For demo assume we are talking to server1. For production,
-    # this should be like "nomad.service.consul:4647" and a system
-    # like Consul used for service discovery.
-    servers = ["127.0.0.1:4647"]
+  # For demo assume we are talking to server1. For production,
+  # this should be like "nomad.service.consul:4647" and a system
+  # like Consul used for service discovery.
+  servers = ["127.0.0.1:4647"]
 }
 
 # Modify our port to avoid a collision with server1 and client1
 ports {
-    http = 5657
+  http = 5657
 }

demo/vagrant/server.hcl

@@ -6,8 +6,8 @@ data_dir = "/tmp/server1"
 
 # Enable the server
 server {
-    enabled = true
+  enabled = true
 
-    # Self-elect, should be 3 or 5 for production
-    bootstrap_expect = 1
+  # Self-elect, should be 3 or 5 for production
+  bootstrap_expect = 1
 }

dist/client.hcl

@@ -2,6 +2,6 @@ bind_addr = "127.0.0.1"
 data_dir = "/var/lib/nomad/"
 
 client {
-	enabled = true
-	servers = ["10.1.0.1", "10.1.0.2", "10.1.0.3"]
-}
+  enabled = true
+  servers = ["10.1.0.1", "10.1.0.2", "10.1.0.3"]
+}

dist/server.hcl

@@ -2,12 +2,12 @@ bind_addr = "0.0.0.0"
 data_dir = "/var/lib/nomad"
 
 advertise {
-	# This should be the IP of THIS MACHINE and must be routable by every node
-	# in your cluster
-	rpc = "1.2.3.4:4647"
+  # This should be the IP of THIS MACHINE and must be routable by every node
+  # in your cluster
+  rpc = "1.2.3.4:4647"
 }
 
 server {
-	enabled = true
-	bootstrap_expect = 3
-}
+  enabled = true
+  bootstrap_expect = 3
+}

website/source/docs/agent/encryption.html.md

@@ -34,7 +34,7 @@ With that key, you can enable gossip encryption on the agent.
 
 Nomad supports using TLS to verify the authenticity of servers and clients. To
 enable this, Nomad requires that all clients and servers have key pairs that are
-generated and signed by a Certificate Authority. This can be a private CA.
+generated and signed by a private Certificate Authority (CA).
 
 TLS can be used to verify the authenticity of the servers and clients. The
 configuration option [`verify_server_hostname`][tls] causes Nomad to verify that
@@ -82,89 +82,10 @@ connections as well as verify proper names on all other certificates.
 Consul will not attempt to health check agents with `verify_https_client` set
 as it is unable to use client certificates.
 
-## Encryption Examples
+# Configuring Nomad with TLS
 
-### TLS Configuration using `cfssl`
+Read the [Configuring TLS Guide][guide] for details on how to configure
+encryption for Nomad.
 
-While [Vault's PKI backend][vault] is an ideal solution for managing
-certificates and other secrets in a production environment, it's useful to use
-simpler command line tools when learning how to configure TLS and your [PKI].
-
-[`cfssl`][cfssl] is a tool for working with TLS certificates and certificate
-authorities similar to [OpenSSL's][openssl] `x509` command line tool.
-
-Once you have the `cfssl` command line tool installed, the first step to
-setting up TLS is to create a Certificate Authority (CA) certificate.  The
-following command will generate a suitable example CA CSR, certificate, and
-key:
-
-```shell
-# Run in the directory where you want to store certificates
-$ cfssl print-defaults csr | cfssl gencert -initca - | cfssljson -bare ca
-```
-
-Next create a `nomad-csr.json` which contains the configuration for the actual
-certificate you'll be using in Nomad:
-
-```json
-{
-  "CN": "global.nomad",
-  "hosts": [
-    "server.global.nomad",
-    "client.global.nomad",
-    "localhost"
-  ]
-}
-```
-
-This will create a certificate suitable for both clients and servers in the
-`global` (default) region.
-
-In production Nomad agents should have a certificate valid for the name
-`${ROLE}.${REGION}.nomad` where role is either `client` or `server` depending
-on the node's role.
-
-Create a certificate signed by your CA:
-
-```shell
-$ cfssl gencert -ca ca.pem -ca-key ca-key.pem nomad-csr.json | cfssljson -bare nomad
-```
-
-You've now successfully generated self-signed certificates! You should see the
-following files:
-
-- `ca.pem` - the CA certificate. This corresponds to the Nomad `ca_file`
-  parameter in the Nomad [`tls` stanza][tls].
-
-- `ca-key.pem` - the CA private key. This is used to sign CSRs and should
-  **not** be included in the Nomad [`tls` stanza][tls].
-
-- `nomad.pem` - the Nomad certificate for the region. This corresponds to the
-  `cert_file` parameter in the Nomad [`tls` stanza][tls].
-
-- `nomad-key.pem` - the Nomad private key. This corresponds to the `key_file`
-  parameter in the Nomad [`tls` stanza][tls].
-
-- `*.csr` - the certificate signing request. This is temporary for generating
-  certificates and should **not** be included in the Nomad [`tls` stanza][tls].
-
-In your Nomad configuration add the `tls` stanza:
-
-```hcl
-tls {
-  http = true
-  rpc  = true
-
-  ca_file   = "ca.pem"
-  cert_file = "nomad.pem"
-  key_file  = "nomad-key.pem"
-
-  verify_server_hostname = true
-}
-```
-
-[vault]: https://www.vaultproject.io/docs/secrets/pki/
-[PKI]: https://en.wikipedia.org/wiki/Public_key_infrastructure
-[cfssl]: https://cfssl.org/
-[openssl]: https://www.openssl.org/
+[guide]: /guides/tls.html "Configuring TLS"
 [tls]: /docs/agent/configuration/tls.html "Nomad TLS Configuration"

website/source/docs/commands/agent.html.md.erb

@@ -35,6 +35,8 @@ via CLI arguments. The `agent` command accepts the following arguments:
 * `-dev`: Start the agent in development mode. This enables a pre-configured
   dual-role agent (client + server) which is useful for developing or testing
   Nomad. No other configuration is required to start the agent in this mode.
+* `-encrypt`: Set the Serf encryption key. See [Agent
+  Encryption](/docs/agent/encryption.html) for more details.
 * `-join=<address>`: Address of another agent to join upon starting up. This can
   be specified multiple times to specify multiple agents to join.
 * `-log-level=<level>`: Equivalent to the [log_level](#log_level) config option.