Merge pull request #735 from joaofnfernandes/dtr-remove

Improve instructions to uninstall DTR

_data/toc.yaml

@@ -771,6 +771,8 @@ toc:
         title: Install offline
       - path: /datacenter/dtr/2.1/guides/install/license/
         title: License your deployment
+      - path: /datacenter/dtr/2.1/guides/install/scale-your-deployment/
+        title: Scale your deployment
       - path: /datacenter/dtr/2.1/guides/install/upgrade/
         title: Upgrade
       - path: /datacenter/dtr/2.1/guides/install/uninstall/

datacenter/dtr/2.1/guides/install/index.md

@@ -35,7 +35,7 @@ install, configure, and backup DTR.
 
 Run the following command to install DTR:
 
-```bash
+```none
 # Pull the latest version of DTR
 $ docker pull docker/dtr
 
@@ -98,14 +98,11 @@ replica fails.
 For high-availability you should set 3, 5, or 7 DTR replicas. The nodes where
 you're going to install these replicas also need to be managed by UCP.
 
-To add replicas to a DTR cluster, use the `docker/dtr join` command. To add
+To add replicas to a DTR cluster, use the `docker/dtr join` command:
-replicas:
 
-1. Make sure the DTR images are loaded into the node.
+1. Load your UCP user bundle.
 
-2. Load you UCP user bundle.
+2.  Run the join command.
-
-3.  Run the join command.
 
     When you join a replica to a DTR cluster, you need to specify the
     ID of a replica that is already part of the cluster. You can find an
@@ -113,14 +110,14 @@ replicas:
 
     Then run:
 
-    ```bash
+    ```none
-    $ docker run -it --rm \
+    docker run -it --rm \
       docker/dtr join \
       --ucp-node <ucp-node-name> \
       --ucp-insecure-tls
     ```
 
-4. Check that all replicas are running.
+3. Check that all replicas are running.
 
     In your browser, navigate to the Docker **Universal Control Plane**
     web UI, and navigate to the **Applications** screen. All replicas should

datacenter/dtr/2.1/guides/install/scale-your-deployment.md

@@ -0,0 +1,63 @@
+---
+title: Scale your deployment
+description: Lean how to scale Docker Trusted Registry by adding and removing replicas.
+keywords: docker, dtr, install, deploy
+---
+
+Docker Trusted Registry is designed to scale horizontally as your usage
+increases. You can add or remove replicas to make DTR scale to your needs
+or for high availability.
+
+To set up DTR for [high availability](../high-availability/index.md),
+you can add more replicas to your DTR cluster. Adding more replicas allows you
+to load-balance requests across all replicas, and keep DTR working if a
+replica fails.
+
+For high-availability you should set 3, 5, or 7 DTR replicas. The nodes where
+you're going to install these replicas also need to be managed by UCP.
+
+## Join more DTR replicas
+
+To add replicas to an existing DTR deployment:
+
+1. Load your UCP user bundle.
+
+2.  Run the join command.
+
+    ```none
+    docker run -it --rm \
+      docker/dtr join \
+      --ucp-node <ucp-node-name> \
+      --ucp-insecure-tls
+    ```
+
+    Where the `--ucp-node` is the hostname of the UCP node where you want to
+    deploy the DTR replica. `--ucp-insecure-tls` tells the command to trust the
+    certificates used by UCP.
+
+3. If you have a load balancer, add this DTR replica to the load balancing pool.
+
+## Remove existing replicas
+
+To remove a DTR replica from a deployment, run:
+
+```none
+docker run -it --rm \
+  docker/dtr remove \
+  --ucp-insecure-tls
+```
+
+You will be prompted for:
+
+* Existing replica id: the id of any healthy DTR replica of that cluster
+* Replica id: the id of the DTR replica you want to remove. It can be the id of an
+unhealthy replica
+* UCP username and password: the administrator credentials for UCP
+
+If you're load-balancing user requests across multiple DTR replicas, don't
+forget to remove this replica from the load balancing pool.
+
+## Where to go next
+
+* [Install DTR](index.md)
+* [Uninstall DTR](uninstall.md)

datacenter/dtr/2.1/guides/install/uninstall.md

@@ -5,56 +5,36 @@ keywords:
 - docker, dtr, install, uninstall
 ---
 
-Use the `remove` command, to remove a DTR replica from a cluster.
+Use the `remove` command, to remove a DTR replica from an existing deployment.
 To uninstall a DTR cluster you remove all DTR replicas one at a time.
-The remove command:
 
-* Removes the replica from the cluster,
+The remove command informs the DTR cluster that the node is about to be removed,
-* Stops and removes all DTR containers,
+then it removes the replica, stops and removes all DTR containers from that node,
-* Deletes all DTR volumes.
+and deletes all DTR volumes.
 
-To see what options are available in the uninstall command, check the
+To uninstall a DTR replica, run:
-[uninstall command reference](../../reference/cli/remove.md), or run:
 
-```bash
+```none
-$ docker run -it --rm docker/dtr remove --help
+docker run -it --rm \
-```
-
-To remove a replica safely, you must tell the bootstrapper about one healthy replica
-using the `--existing-replica-id` flag and the replica to remove with the
-`--replica-id` flag. It uses the healthy replica to safely inform your DTR cluster
-that the replica is about to be removed before it performs the actual removal.
-
-## Example
-
-The following example illustrates how use the remove command interactively to
-remove a DTR replica from a cluster with multiple replicas:
-
-```bash
-
-$ docker run -it --rm \
   docker/dtr remove \
   --ucp-insecure-tls
-
-existing-replica-id (ID of an existing replica in a cluster): 7ae3cb044b70
-replica-id (Specify the replica Id. Must be unique per replica, leave blank for random): a701a510126c
-ucp-username (Specify the UCP admin username): $UCP_ADMIN
-ucp-password: $UCP_PASSWORD
-ucp-url (Specify the UCP host using the host[:port] format): $UCP_HOST
 ```
 
-Where:
+You will be prompted for:
 
-* existing-replica-id: is the id of any healthy DTR replica of that cluster,
+* Existing replica id: the id of any healthy DTR replica of that cluster
-* replica-id: is the id of the DTR replica you want to remove,
+* Replica id: the id of the DTR replica you want to remove. It can be the id of an
-* ucp-username and ucp-password: are the username and password of a UCP administrator.
+unhealthy replica that you want to remove from your deployment
+* UCP username and password: the administrator credentials for UCP
 
+To ensure you don't loose data, DTR will not remove the last replica from your
+deployment. To confirm you really want to remove that replica, use the
+`--force-remove` flag.
 
-Now you can confirm on Docker Universal Control Plane that the DTR replica
+To see what options are available in the uninstall command, check the
-`a701a510126c` no longer exists.
+[uninstall command reference documentation](../../reference/cli/remove.md).
-
 
 ## Where to go next
 
+* [Scale your deployment](scale-your-deployment.md)
 * [Install DTR](index.md)
-* [Install DTR offline](install-offline.md)