Make HA and CA Replication Docs More Straightforward

Makes several changes to docs related to making high availability and
CA replication more straightforward.

This is essentially PR #1856, with a few edits.
Closes #1856.

high-availability/replicate-cas.md

@@ -54,19 +54,24 @@ every controller node:
 ## Backup the certificates and keys
 
 To create a backup of the root certificates and keys used by the CAs, use the
-backup command. Notice that this command stops the UCP containers, so you
-should use it outside business peak hours.
+backup command. Notice that this command temporarily stops the UCP CA
+containers, so you should use it outside business peak hours.
+
+Log into the node using ssh, and run:
 
 ```bash
 $ docker run --rm -i --name ucp \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    docker/ucp backup --root-ca-only --passphrase "secret" > /tmp/backup.tar
+    docker/ucp backup --root-ca-only --interactive \
+    --passphrase "secret" > /tmp/backup.tar
 ```
 
 Where:
 
-* root-ca-only, specifies to only backup the CA certificates and keys,
-* passphrase, encrypts the backup with a given passphrase
+* `root-ca-only` specifies to only backup the CA certificates and keys.
+* `interactive` makes the command prompt for any information it needs.
+* `passphrase` encrypts the backup with a given passphrase.
+* `> backup.tar` streams the backup output to a file.
 
 ## Restore the certificate and keys
 
@@ -74,18 +79,21 @@ Once you have a backup archive of the certificates and keys used by the CAs
 of a controller node, you can use it to make CAs in other controller nodes
 use the same certificate and private key.
 
-You can use the restore command for this:
+Log into the node using ssh, and run:
 
 ```bash
 $ docker run --rm -i --name ucp \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    docker/ucp restore --root-ca-only --passphrase "secret" < /tmp/backup.tar
+    docker/ucp restore --root-ca-only --interactive \
+    --passphrase "secret" < /tmp/backup.tar
 ```
 
 Where:
 
-* root-ca-only, specifies to only restore the volumes used by the CAs,
-* passphrase, specifies the passphrase to decrypt the backup archive.
+* `root-ca-only` specifies to only restore the volumes used by the CAs.
+* `interactive` makes the command prompt for any information it needs.
+* `passphrase` specifies the passphrase to decrypt the backup archive.
+* `< backup.tar`, reads input from the backup.tar file.
 
 ## Where to go next
 

high-availability/set-up-high-availability.md

@@ -50,6 +50,12 @@ decreases. Don't leave that replica offline for long.
 degradation, as changes to configurations need to be replicated across all
 replicas.
 
+## Replicating CAs
+
+When configuring UCP for high-availability, you need to ensure the CAs running
+on each UCP controller node are interchangeable. This is done by transferring
+root certificates and keys for the CAs to each controller node on the cluster. 
+[Learn how to replicate CAs for high availability](replicate-cas.md)
 
 ## Load-balancing on UCP
 

installation/install-production.md

@@ -32,20 +32,16 @@ Engine.
 
 ## Step 3: Customize named volumes
 
-This step is optional.
-
 Docker UCP uses [named volumes](../architecture.md) to persist data. If you want
 to customize the volume drivers and flags of these volumes, you can create the
 volumes before installing UCP.
 
-If the volumes don't exist, when installing UCP they are
-created with the default volume driver and flags.
+If the volumes don't exist, when installing UCP they are created with the
+default volume driver and flags.
 
 
 ## Step 4: Customize the CA used
 
-This step is optional.
-
 The UCP cluster uses TLS to secure all communications. Two Certificate
 Authorities (CA) are used for this:
 
@@ -128,16 +124,26 @@ Now that your UCP controller is installed, you need to license it.
 
 ## Step 7: Backup the controller CAs
 
-This step is optional.
-
 For an highly available installation, you can add more controller nodes to
 the UCP cluster. The controller nodes are replicas of each other.
 [Learn more about high-availability](../high-availability/set-up-high-availability.md).
 
-For this, you need to make the CAs on each controller node, use the same
+For this, you need to make the CAs on each controller node use the same
 root certificates and keys.
 [Learn how to replicate the CAs for high availability](../high-availability/replicate-cas.md).
 
+This requires creating a backup of the controller for the purposes of
+replicating the root CA. Your backup command might look like this:
+
+```bash
+$ docker run --rm -i --name ucp \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    docker/ucp backup --root-ca-only --interactive \
+    --passphrase "secret" > /tmp/backup.tar
+```
+
+`--passphrase` encrypts the backup with the provided passphrase; this is
+optional but recommended for security purposes.
 
 ## Step 8: Add controller replicas to the UCP cluster
 
@@ -149,19 +155,22 @@ the UCP cluster. For that, use the `docker/ucp join --replica` command.
 
 For each node that you want to install as a controller replica:
 
-1. Log into that node.
+1. Log into that node using ssh.
 
-2. Use the join command with the replica option:
+2. Make sure you transfer the backup.tar from the previous step to this node.
+
+3. Use the join command with the replica option:
 
     In this example we'll be running the join command interactively, so that
-    the command prompts for the necessary configuration values.
-    You can also use flags to pass values to the install command.
+    the command prompts for the necessary configuration values. We'll also
+    be passing the backup.tar file from the previous step in order to ensure
+    that the CAs are replicated to the new controller node.
 
     ```bash
     $ docker run --rm -it --name ucp \
       -v /var/run/docker.sock:/var/run/docker.sock \
-      docker/ucp join -i \
-      --replica
+      -v $BACKUP_PATH/backup.tar:/backup.tar \
+      docker/ucp join -i --replica
     ```
 
 3. Since UCP configures your Docker Engine for multi-host networking, it might

reference/backup.md

@@ -49,3 +49,4 @@ built-in PGP compatible encryption.
 | `--id`           | The ID of the UCP instance to backup                                    |
 | `--root-ca-only` | Backup only the root CA certificates and keys from this controller node |
 | `--passphrase`   | Encrypt the tar file with the provided passphrase [$UCP_PASSPHRASE]     |
+| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. |

reference/restore.md

@@ -47,3 +47,4 @@ must be provided.
 | `--id`           | The ID of the UCP instance to backup                                                                   |
 | `--root-ca-only` | Restore only the root CA certificates and keys on this controller node (leaving all other data intact) |
 | `--passphrase`   | Decrypt the tar file with the provided passphrase [$UCP_PASSPHRASE]                                    |
+| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information.                    |