Rancher: Part 1 - Installation and Configuration

Welcome to part 1 of a multi-part series where I will walk through the setup and configuration of Rancher.

In the previous post, I introduced you to Rancher and briefly discussed the problems I am attempting to solve.

In this post I will show you how easy it is to setup a Rancher deployment and configure the Rancher NFS service so volume data is persisted on an NFS share.

Create some Virtual Machines, Install CentOS and Docker

For my deployment, I decided to setup a non-HA Rancher Server and three Rancher Hosts to run the workload. I considered setting up an HA Rancher deployment but my needs suggest something simpler. It's not the end of the world, for me, if the server goes down and I backup my VMs daily. Worst case scenario, I recover the backup and am back up and running in a few hours. That said, the HA Rancher Installation Instructions are pretty clear about how to setup an HA system if you so desire.

For my deployment, I decided to have two different VM flavors. One for the Server and one for the Hosts:

  • Server - 2 vCPU, 4GB Memory, 40GB Disk
  • Hosts - 6 vCPU, 12GB Memory, 60GB Disk

Going to my vSphere deployment, I created one Server VM and three Host VMs. I then proceeded to install CentOS 7 on each of them. I used the CentOS-7-x86_64-Minimal-1511.iso image to install as I had it handy and was going to update all the packages anyway. Any modern Linux distro that can run Docker 1.10.3+ should work fine.

After installing CentOS and configuring static IP addresses, I updated all the packages, installed Docker, and disabled SELinux. Had the CentOS firewall been installed for me, I would have disabled it. It appears that CentOS minimal does not include firewalld so I skipped that step. The steps I used were:

  • Enable my user for sudo. While this is, technically, not needed... I always use sudo to protect myself from mistakes. I created a file called /etc/sudoers.d/eric with the content of:

    ## Allow eric to run any commands anywhere
    eric  ALL=(ALL)   ALL
  • Run the following commands:

    sudo yum update
    curl -fsSL https://get.docker.com/ | sh
    sudo systemctl enable docker.service
    sudo systemctl start docker
    sudo usermod -aG docker eric
  • modify /etc/sysconfig/selinux to disable SELinux. The resulting file should look like

    # This file controls the state of SELinux on the system.
    # SELINUX= can take one of these three values:
    #     enforcing - SELinux security policy is enforced.
    #     permissive - SELinux prints warnings instead of enforcing.
    #     disabled - No SELinux policy is loaded.
    SELINUX=disabled
    # SELINUXTYPE= can take one of these three values:
    #     targeted - Targeted processes are protected,
    #     minimum - Modification of targeted policy. Only selected processes are protected.
    #     mls - Multi Level Security protection.
    SELINUXTYPE=targeted
  • reboot the node
    sudo reboot

Once the machine comes back up, it is ready to have Rancher installed!

I also configured DNS entries for the four nodes. 'rancher' is the server and 'rancher1', 'rancher2', and 'rancher3' are the hosts which will run containers. Configuring DNS is optional but helps me remember things

Rancher Server Installation

Alright! Now that we have some Virtual Machines created, let's deploy the Rancher Server. This really could not be any simpler.

Originally, I simply ran the rancher/server but then I realized that upgrading would be a pain as that would cause rancher to use a mysql database INSIDE it's own container for persistence. Instead, I went to my mysql server (I run a mysql server for just this kind of reason) and created a database for Rancher. I used phpmyadmin for this but the commands documented in the Rancher Installation Guide should work as well (please choose a better password):

CREATE DATABASE IF NOT EXISTS cattle COLLATE = 'utf8_general_ci' CHARACTER SET = 'utf8';
GRANT ALL ON cattle.* TO 'cattle'@'%' IDENTIFIED BY 'password';
GRANT ALL ON cattle.* TO 'cattle'@'localhost' IDENTIFIED BY 'password';

Then, log onto the server and start up a container with the following command:

sudo docker run -d --restart=unless-stopped -p 80:8080 --name=rancher-server rancher/server:stable --db-host database.host.name --db-port 3306 --db-user cattle --db-pass password --db-name cattle

Note a couple of things I did there:

  • Started the container in the background (-d)
  • Told Docker to restart the container if it fails (--restart=unless-stopped)
  • Mapped the Rancher GUI to port 80 (-p 80:8080)
  • Named the image 'rancher-server' (--name=rancher-server)
  • Told docker to pull/run the 'stable' version. They also publish a 'latest' label
  • Passed in the database arguments. Using an external database means that upgrading Rancher is as simple as stopping the old container and starting the new!

After pulling the newest 'stable' image from the Docker Hub, the service gets started. If you're unsure if the image is running or not, you can check by running docker ps. It should show you a running image named rancher-server.

Docker Server

Assuming the Rancher Server started up, you should be able to open a browser and navigate to the UI. It took a couple of seconds for the UI to become available but everything seems to have come up fine. Success!

Docker UI

Rancher Host Installation

Adding a Rancher host is even easier. From the Rancher UI, go to the "Infrastructure" menu and select "hosts". There should be a blue button on the top left that says "Add Host". The instructions there have 6 steps but the only one I worried about was step 5 that asks you to copy and paste a command to run on the host you want to add. In my case, the command was:

sudo docker run -d --privileged -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/rancher:/var/lib/rancher rancher/agent:v1.1.2 http://rancher.internal.aceshome.com/v1/scripts/0E866B98A276EFE250B8:1483995600000:fclzMSBZmJJ5pUcFqHRzeaKXx6Q

I copied and pasted that on all three hosts I wanted to add. It downloads and starts several containers but after a couple of minutes, my "Hosts" list was populated with all three hosts!

Docker Hosts

The basic system is now up and running. I want to configure a couple of things and we're done!

Rancher Configuration

The only configuration I changed was to enable authentication. Under the "Admin" menu is an item called "Access Control". Once you select that menu item, there are several options as to how to authenticate to Rancher. I chose to use github.com and there were really good instructions right on the page as to how to do that so I will not repeat it here.

If you are setting up a private Rancher instance (as I am), you might be able to leave it wide open but I wanted to try it out anyway.

Rancher NFS Installation

Next up, I wanted to try out configuring the Rancher NFS support. There is a fairly good explanation of how to do this on the Rancher website.

In my case, I wanted to configure the Rancher NFS service such that volumes were created on a Synology NAS server. I simply created a share dedicated to this purpose via the Synology and then returned to the Rancher UI to complete the tasks. First, you have to deploy a service from the catalog, it is called "Rancher NFS". Find it in the catalog and select it. There were a couple of parameters it asked for:

  • NFS Server: This is the hostname or ip address of the NFS server
  • Mount Directory: The directory that Rancher should Mount
  • Mount Options: These are options that are passed to the NFS client and can safely be left blank unless you know you need specific options.

Fill in the fields and press the "Launch" button. Rancher will then deploy the service on all of your Rancher Hosts.

I wanted to validate that it worked, so I looked at the example on the Rancher website and there was an example docker-compose file that spins up an Ubuntu container with a volume mounted. The example is slightly out of date (the volume_driver is now called 'rancher-nfs') but should be as follows:

test:
 image: ubuntu
 volume_driver: rancher-nfs
 tty: true
 volumes:
 - test_volume:/data
 command:
 - bash

I created a stack and pasted in the docker-compse.yml content above. Rancher started up an Ubuntu container. I then logged onto the host and used docker exec to enter the container; once in, I write a file to the /data filesystem. Going back to my Synology NAS, I checked my NFS share and saw the file had been created.

So.... it looks like it works well. I can now create volumes that are backed by NAS and accessible on all my Rancher hosts!

Next Up...

Default Catalog