From 2fe671eed64c76a48af45a5fb3aa446ca5686340 Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Wed, 27 Apr 2016 11:01:51 -0700 Subject: [PATCH] Adds docs about replicating CAs Adds new docs on how to use backup and restore commands to replicate certificates and keys used on all controller nodes. --- .../backups-and-disaster-recovery.md | 2 +- high-availability/replicate-cas.md | 92 +++++++++++++++++++ high-availability/set-up-high-availability.md | 3 +- installation/install-production.md | 13 ++- 4 files changed, 105 insertions(+), 5 deletions(-) create mode 100644 high-availability/replicate-cas.md diff --git a/high-availability/backups-and-disaster-recovery.md b/high-availability/backups-and-disaster-recovery.md index 30c24c6517..8dc512c164 100644 --- a/high-availability/backups-and-disaster-recovery.md +++ b/high-availability/backups-and-disaster-recovery.md @@ -5,7 +5,7 @@ description="Learn how to backup your Docker Universal Control Plane cluster, an keywords= ["docker, ucp, backup, restore, recovery"] [menu.main] parent="mn_ucp_high_availability" -weight=10 +weight=20 +++ diff --git a/high-availability/replicate-cas.md b/high-availability/replicate-cas.md new file mode 100644 index 0000000000..7a4371d982 --- /dev/null +++ b/high-availability/replicate-cas.md @@ -0,0 +1,92 @@ + + +# Replicate CAs for high availability + +Internally, UCP uses two Certificate Authorities: + +* `ucp-cluster-root-ca` signs the certificates that are used by new nodes +joining the cluster. This CA also generates the certificates for admin client +certificate bundles. +* `ucp-client-root-ca` signs non-admin client certificate bundles. + +When configuring UCP for high-availability, you need to ensure the CAs running +on each UCP controller node are interchangeable. This is done by using the same +root certificates and keys for every CA on the cluster. + + +## Replicating the CAs across controller nodes + +There are two ways to ensure the same root certificates and keys are used on +every controller node: + +* When joining a controller node: + + When you install the first controller node, root certificates and keys are + automatically generated. + After installing the first controller node, you can backup the certificates + and keys used by that controller using. + + + Then, when joining new controller nodes to the cluster, you use the use + the backup you've created to make the CAs in both nodes use the same root + certificates and keys. + +* After joining all controller nodes: + + Alternatively, you can replicate root certificates and keys through all + controller nodes after you've joined them to the cluster. + + After the installation, you backup the root certificates and keys of the + controller that had the valid CA material and restore all other controllers + with that backup archive, one by one. + + +## 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. + +```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 +``` + +Where: + +* root-ca-only, specifies to only backup the CA certificates and keys, +* passphrase, encrypts the backup with a given passphrase + +## Restore the certificate and keys + +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: + +```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 +``` + +Where: + +* root-ca-only, specifies to only restore the volumes used by the CAs, +* passphrase, specifies the passphrase to decrypt the backup archive. + +## Where to go next + +* [Set up high availability](set-up-high-availability.md) +* [Backups and disaster recovery](backups-and-disaster-recovery.md) diff --git a/high-availability/set-up-high-availability.md b/high-availability/set-up-high-availability.md index b77927f25a..2d9910d0de 100644 --- a/high-availability/set-up-high-availability.md +++ b/high-availability/set-up-high-availability.md @@ -3,9 +3,10 @@ aliases = [ "/ucp/understand_ha/"] title ="Set up high availability" description="Docker Universal Control plane has support for high availability. Learn how to set up your installation to ensure it tolerates failures." -keywords= ["replica, controller, availability, high, ucp"] +keywords= ["docker, ucp, high-availability, replica"] [menu.main] parent="mn_ucp_high_availability" +weight=0 +++ diff --git a/installation/install-production.md b/installation/install-production.md index ac06f9e113..4426cd0eb3 100644 --- a/installation/install-production.md +++ b/installation/install-production.md @@ -112,13 +112,20 @@ To install UCP: Now that your UCP controller is installed, you need to license it. [Learn how to license your installation](license.md). -## Step 6: Add controller replicas to the UCP cluster +## Step 6: Backup the controller CAs Docker UCP has support for high-availability. For an highly available installation, you 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). +When configuring UCP for high-availability, you need to ensure the CAs running +on each UCP controller node are interchangeable. This is done by using the same +certificates and keys for every CA on the cluster. +[Learn how to replicate the CAs for high availability](../high-availability/replicate-cas.md). + +## Step 7: Add controller replicas to the UCP cluster + To add more controller nodes to the cluster, use the `docker/ucp join --replica` command. To find what commands and options are available, check the [reference documentation](../reference/join.md), or run: @@ -155,7 +162,7 @@ For each node that you want to install as a controller replica: ![UCP nodes page](../images/replica-nodes.png) -## Step 7: Add more nodes to the UCP cluster +## Step 8: Add more nodes to the UCP cluster Now you can add additional nodes to your UCP cluster. These are the nodes that will be running your containers. @@ -180,7 +187,7 @@ For each node that you want to add to your UCP cluster: ![UCP nodes page](../images/nodes-page.png) -## Step 8. Download an admin user bundle +## Step 9. Download an admin user bundle To validate that your cluster is correctly configured, you should try accessing the cluster with the Docker CLI client. For this, you'll need to get a client