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.

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
 +++
 <![end-metadata]-->
 

high-availability/replicate-cas.md

@@ -0,0 +1,92 @@
+<!--[metadata]>
++++
+title ="Replicate CAs for 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"]
+[menu.main]
+parent="mn_ucp_high_availability"
+weight=10
++++
+<![end-metadata]-->
+
+# 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)

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
 +++
 <![end-metadata]-->
 

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