docker/docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-05 00:14:17 +03:00
Code Activity

Updates upgrade docs

Browse Source 
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
This commit is contained in:
Joao Fernandes
2016-05-16 13:31:42 -07:00
parent c11a1a0a7b
commit 799cf70b9a
1 changed files with 59 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
installation/upgrade.md
View File

@@ -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 $(<env.sh)
$ docker info
$ 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.
```
3. <a name="no-ha-step-3"></a>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. <a name="no-ha-step-4"></a>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 $(<env.sh)
$ docker info
```
4. Ensure no administrator user makes configuration changes during the upgrade.
3. Ensure no administrator user makes configuration changes during the upgrade.
The UCP cluster uses an internal key-value store to save configuration
settings, like the method used for authenticating users. For
@@ -204,8 +147,7 @@ If your cluster is set up for high-availability (has several replica nodes):
To avoid misconfigurations, ensure no administrator changes UCP
configurations during the upgrade.
5. <a name="ha-step-5"></a>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. <a name="ha-step-6"></a>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. <a name="ha-step-7"></a>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. <a name="ha-step-8"></a>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