From 54836e90fc4c0bc8567ec4cdfcf740e0f803ebd6 Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Mon, 16 May 2016 13:31:42 -0700 Subject: [PATCH] Updates upgrade docs Updates upgrade documentation to make sure `docker/ucp upgrade` command is run inside the node, and not agains the UCP cluster, or swarm. Fixes #1050 --- installation/upgrade.md | 194 ++++++++++++---------------------------- 1 file changed, 59 insertions(+), 135 deletions(-) diff --git a/installation/upgrade.md b/installation/upgrade.md index 191ba9442f..1ede60a297 100644 --- a/installation/upgrade.md +++ b/installation/upgrade.md @@ -27,15 +27,10 @@ to misconfigurations that are difficult to troubleshoot. ## The UCP upgrade command -To upgrade a UCP installation, you run the `ucp upgrade` command on each node -of the cluster. To find what are available, check the -[reference documentation](../reference/upgrade.md), or run: +To upgrade a UCP installation, you run the `docker/ucp upgrade` command on +each node of the cluster. -```bash -$ docker run --rm -it docker/ucp upgrade --help -``` - -When you run the `upgrade` command, it: +When you run the upgrade command, it: 1. Pulls the images of the new UCP version from Docker Hub. 2. Checks if it is possible to upgrade directly to the new version. @@ -84,79 +79,48 @@ if your cluster has multiple controller nodes. If your cluster is not set up for high-availability (does not have replica nodes): -1. Make sure you have an admin client bundle. +1. Make sure your cluster is healthy before starting the upgrade. - You can use a client bundle to make the Docker client connect to the - Docker Engine running on the node. This way, you won't have to use - ssh to connect directly to the hosts you want to upgrade. + Login into the **UCP UI** and navigate to the **Nodes** page. Make sure + all nodes are listed and healthy. - To download a client bundle, **login** with an administrator user, - go to your **profile** and click the **Create a Client Bundle** button. +2. Log into the controller node using ssh. - ![Create a client bundle](../images/add-pk.png) - -2. Make sure your cluster is healthy before starting the upgrade. - - Login into **UCP** and navigate to the **Nodes** page. Make sure all nodes - are listed. - - ![UCP nodes](../images/cluster-nodes.png) - - You can also use your client bundle for this. In the command line, navigate - to the directory of the client bundle and run: +3. Upgrade the controller node. ```bash - $ eval $(Upgrade the controller node. +4. Delete your browser cache. - ```bash - $ docker --host=tcp://[controller-ip]:[engine-port] run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp upgrade -i - ``` + Your browser can continue serving cached pages from the older version of + UCP. To avoid errors on the UCP UI, ensure you delete the browser cache. - The `--host` option allows you to specify the IP and port of the Docker - Engine running on the controller node. - - If the controller node is on a separate network, or there are firewall - rules blocking requests to the Docker Engine port, you might need - to connect directly to the machine using ssh. - - When running the `upgrade` command, you should have the following result: - - ```bash - $ docker --host=tcp://192.168.99.100:12376 run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp upgrade -i - - # INFO[0000] We're about to upgrade the local components for UCP ID: KRIJ:UEYA:AGTD:6BBO:AHS7:QSPA:ZFAM:X7KW:GNXR:4MWQ:UDPU:MRGR - Do you want proceed with the upgrade? (y/n): y - - # INFO[0028] All required images are present - # INFO[0000] Checking for version compatibility - # INFO[0000] Your system is compatible. Removing old UCP Containers while preserving data - # INFO[0000] Redeploying UCP containers - # INFO[0002] Verifying containers started - # INFO[0004] Success! Please log in to the UCP console to verify your system before proceeding to upgrade additional nodes. - ``` - -4. Make sure the controller node is healthy. +5. Make sure the controller node is healthy. In your browser, navigate to the **UCP web app**, to make sure the controller is running. Navigate to the **Nodes** page, - to make sure the controller is healthy. + to make sure the node is healthy. - You can also use the `docker info` command from the CLI for this. - -5. For all other nodes in the cluster: - 1. Upgrade that node, using the instructions in [step 3](#no-ha-step-3). - 2. Make sure that node is healthy, using the instructions - in [step 4](#no-ha-step-4). - -6. Make sure to flush your browser's cache prior to to running the upgraded UCP in the UI. +6. Upgrade all other nodes in the cluster using steps 2-5. ### My cluster is set for high-availability -If your cluster is set up for high-availability (has several replica nodes): +If your cluster is set up for high-availability (has several controller nodes): 1. Schedule the upgrade to take place outside business hours. @@ -164,33 +128,12 @@ If your cluster is set up for high-availability (has several replica nodes): upgrading outside business hours ensures the impact on your business is close to none. -2. Make sure you have an admin client bundle. +2. Make sure your cluster is healthy before starting the upgrade. - You can use a client bundle to make the Docker client connect to the - Docker Engine running on the node. This way, you won't have to use - ssh to connect directly to the hosts you want to upgrade. + Login into the **UCP UI** and navigate to the **Nodes** page. Make sure all + nodes are listed and healthy. - To download a client bundle, **login** with an administrator user, - go to your **profile** and click the **Create a Client Bundle** button. - - ![Create a client bundle](../images/add-pk.png) - -3. Make sure your cluster is healthy before starting the upgrade. - - Login into **UCP** and navigate to the **Nodes** page. Make sure all nodes - are listed. - - ![UCP nodes](../images/cluster-nodes.png) - - You can also use your client bundle for this. In the command line, navigate - to the directory of the client bundle and run: - - ```bash - $ eval $(Block user access to the controller node. +4. Block user access to the controller node. This can be done by setting the load balancer to drain existing connections to the controller node. @@ -217,60 +159,42 @@ If your cluster is set up for high-availability (has several replica nodes): This way users can continue using UCP, while the controller node is being upgraded. -6. Upgrade the controller node. +5. Log into the controller node using ssh. + +6. Upgrade the controller node. ```bash - $ docker --host=tcp://[controller-ip]:[engine-port] run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp upgrade -i + $ docker run --rm -it \ + --name ucp \ + -v /var/run/docker.sock:/var/run/docker.sock \ + docker/ucp upgrade -i + + # INFO[0000] We're about to upgrade the local components for UCP ID: KRIJ:UEYA:AGTD:6BBO:AHS7:QSPA:ZFAM:X7KW:GNXR:4MWQ:UDPU:MRGR + Do you want proceed with the upgrade? (y/n): y + + # INFO[0028] All required images are present + # INFO[0000] Checking for version compatibility + # INFO[0000] Your system is compatible. Removing old UCP Containers while preserving data + # INFO[0000] Redeploying UCP containers + # INFO[0002] Verifying containers started + # INFO[0004] Success! Please log in to the UCP console to verify your system before proceeding to upgrade additional nodes. ``` - The `--host` option allows you to specify the IP and port of the Docker - Engine running on the controller node. +7. Delete your browser cache. - If the controller node is on a separate network, or there are firewall - rules blocking requests to the Docker Engine port, you might need - to connect directly to the machine using ssh. + Your browser can continue serving cached pages from the older version of + UCP. To avoid errors on the UCP UI, ensure you delete the browser cache. - When running the `upgrade` command, you should have the following result: +8. Make sure the controller node is healthy. - ```bash - $ docker --host=tcp://192.168.99.100:12376 run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp upgrade -i - - # INFO[0000] We're about to upgrade the local components for UCP ID: KRIJ:UEYA:AGTD:6BBO:AHS7:QSPA:ZFAM:X7KW:GNXR:4MWQ:UDPU:MRGR - Do you want proceed with the upgrade? (y/n): y - - # INFO[0028] All required images are present - # INFO[0000] Checking for version compatibility - # INFO[0000] Your system is compatible. Removing old UCP Containers while preserving data - # INFO[0000] Redeploying UCP containers - # INFO[0002] Verifying containers started - # INFO[0004] Success! Please log in to the UCP console to verify your system before proceeding to upgrade additional nodes. - ``` - -7. Make sure the controller node is healthy. - - In your browser, navigate to the UCP web app. In the **Nodes** page + In your browser, navigate to the **UCP web app**. In the **Nodes** page confirm that the controller is running, and the cluster is healthy. - You can also do this on the CLI with the `docker info` command. +9. Add the controller node back to the load balancing pool. -8. Add the controller node back to the load balancing pool. +10. Upgrade other controller nodes one at a time, using steps 4-9. -9. For each replica node in the cluster: - 1. Stop users from accessing that replica, using the instructions - in [step 5](#ha-step-5). - 2. Upgrade the replica node, using the instructions - in [step 6](#ha-step-6). - 3. Make sure the replica node is healthy, using the instructions - in [step 7](#ha-step-7). - 4. Allow users to make requests to the replica, using the instructions in - [step 8](#ha-step-8). - -10. For all other nodes in the cluster: - 1. Upgrade that node, using the instructions in [step 6](#ha-step-6). - 2. Make sure the node is healthy, using the instructions - in [step 7](#ha-step-7). - -11. Make sure to flush your browser's cache prior to to running the upgraded UCP in the UI. +11. Upgrade other nodes in the cluster, using steps 5-8. ## Where to go next