Upgrading Rancher v1.x & Docker

Initial notes

1. If you are in doubt or instruction are unclear/outdated, always refer to the latest documentation.
2. Throughout this guide {rancher_version} will represent a Rancher version including and up to the minor semver field (e.g.: v1.6).

Upgrading Rancher

Note: The following instructions are valid for the simplest non-HA permanent deploy of Rancher (referred to in the docs as SINGLE CONTAINER (NON-HA) - BIND MOUNTED MYSQL VOLUME).

1. Check the latest documentation to see if anything obvious has changed or for the presence of warnings of any kind: http://rancher.com/docs/rancher/{rancher_version}/en/upgrading/.

2. Stop the Rancher server container (adjust the container name to fit yours).

1

docker stop rancher-server

3. Ensure that the folder containing Rancher’s MySQL database has the correct permissions for the container engine to access it (UID and GID are standard for every Rancher installation, they don’t rely on the host’s users/groups).

1

chown -R 102:105 /path/to/your/rancher/mysql-data

4. Update your local Rancher server image (use latest instead of stable if you want to obtain the absolute latest version instead of the one recommended for production).

1

docker pull rancher/server:stable

5. Restart the main Rancher container with the needed options (choose one from below) - make sure to append /mysql to Rancher’s MySQL folder path on host as the examples here do!

   • Simple setup with no extra capabilities enabled:

     1	docker run -d -v /path/to/your/rancher/mysql-data/mysql:/var/lib/mysql --restart=unless-stopped -p 8080:8080 --name rancher-server-1 rancher/server:stable

   • Setup with Prometheus monitoring enabled:

     1	docker run -d -v /path/to/your/rancher/mysql-data/mysql:/var/lib/mysql --restart=unless-stopped -e CATTLE_PROMETHEUS_EXPORTER=true -p 8080:8080 -p 9108:9108 --name rancher-server-1 rancher/server:stable

6. Verify that the new container has started correctly; I usually let it run for a few minutes to check that it doesn’t crash.

1
2

docker ps | sed '1b;/rancher-server-1/!d'
docker logs -f rancher-server-1

7. If everything went smoothly, remove the old container…

1

docker rm rancher-server

8. …And rename the new one.

1

docker rename rancher-server-1 rancher-server

The last step is upgrading Rancher’s internal services too; login to your dashboard and, for every Cattle environment that you have, in the Stacks > Infrastructures section upgrade the stacks in the following order:

• network-policy-manager
• network-services
• ipsec
• All the other stacks

Remember to wait for a service to have completely finished (and user-confirmed via UI) its update before moving on to the next one.

Rancher’s Agents are binded to Rancher’s own version and are automatically managed by itself on the hosts, there’s no need to worry about them.

Upgrading Docker

Note: These instructions contian Debian-specific commands, but the general concepts apply on every distro. It is also given that you have the Docker repo already set up in your system.

1. Check on the official docs which versions of Docker your current Rancher version supports: http://rancher.com/docs/rancher/{rancher_version}/en/hosts/#supported-docker-versions

2. Update your local repo caches as usual.

1

sudo apt-get update

3. Show which Docker versions are available.

1
2

apt-cache madison docker-ce
apt-cache policy docker-ce

4. If needed and supported by Rancher, upgrade your Docker version (replace {DOCKER_VERSION} with your chosen one).

1
2

sudo apt-mark unhold docker-ce
sudo apt-get install docker-ce={DOCKER_VERSION}

6. You can either restart Docker’s SystemD service or go with a full host reboot.

1

sudo systemctl restart docker.service

7. After the restart (of either the service or the host), check Docker’s status.

1
2

systemctl status docker.service
journalctl -fu docker

8. If any problems arise, try to wait 15-30mins for them to resolve by themselves - some combinations of Rancher/Docker upgrades can lead to slight incompatibility between components, causing timeouts and reconfigurations at the first start. If problems persist for longer or after a reboot, you can either roll back to the previous Docker version or dig deeper into SystemD’s journal to find the root of troubles.

9. OPTIONAL: If nothing went wrong, prevent the accidental upgrade of Docker’s package in the future:

1

sudo apt-mark hold docker-ce