From fbb510c272e1f94b423de50a99e33f8f90554b9b Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Wed, 8 Jun 2016 13:38:35 -0700 Subject: [PATCH] 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 | 26 ++++++++----- high-availability/set-up-high-availability.md | 6 +++ installation/install-production.md | 39 ++++++++++++------- reference/backup.md | 1 + reference/restore.md | 1 + 5 files changed, 49 insertions(+), 24 deletions(-) diff --git a/high-availability/replicate-cas.md b/high-availability/replicate-cas.md index cd43a6d0d9..d65abe65f2 100644 --- a/high-availability/replicate-cas.md +++ b/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 diff --git a/high-availability/set-up-high-availability.md b/high-availability/set-up-high-availability.md index bc12fa3fb7..6d1a2405f7 100644 --- a/high-availability/set-up-high-availability.md +++ b/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 diff --git a/installation/install-production.md b/installation/install-production.md index 62be0ecdcc..63ea640aa1 100644 --- a/installation/install-production.md +++ b/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 diff --git a/reference/backup.md b/reference/backup.md index e3faec3ca7..c228e72df4 100644 --- a/reference/backup.md +++ b/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. | \ No newline at end of file diff --git a/reference/restore.md b/reference/restore.md index de5b3bcd35..e358acf2b4 100644 --- a/reference/restore.md +++ b/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. |