Migrating from Rancher 1.6 to Rancher 2.0 - A Short Checklist

Rancher 1.6 is a widely used container orchestration platform that runs and manages Docker and Kubernetes in production. Cattle is the base orchestration engine for Rancher 1.6 that is being used by many opensource and enterprise setups.

With the release of Rancher 2.0, we shifted from Cattle as the base orchestration platform to Kubernetes. As aptly noted here, Rancher 2.0 aims at helping users align with the Kubernetes Everywhere reality of the infrastructure and cloud domain.

However Rancher 2.0 differs from Rancher 1.6 because it brings in a new orchestration technology, Kubernetes. Currently, there is no straightforward upgrade path available between these versions.

So as a Rancher 1.6 user who’s interested in moving to 2.0, what steps should you take?

Checklist for Migration

In this article, I will provide a short checklist you can follow to do the migration:

Installation

Instructions for a Rancher 2.0 installation can be found in the Rancher Documentation.

Note that the Docker versions currently supported by Rancher 2.0 are:

• 1.12.6
• 1.13.1
• 17.03.2

This list is per the validated Docker versions found under External Dependencies in the Kubernetes upstream release.

For Kubernetes, Rancher currently uses the 1.10 version and is planning to go with the 1.11 version in the upcoming 2.0.7 release. Rancher will keep updating to the most-recent upstream Kubernetes releases.

For a basic single node dev installation, you would provision a single Linux host with Docker and install Rancher within a Docker container using the familiar docker run command, just like the Rancher 1.6 installation.

  docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  rancher/rancher:latest

For development environments, we recommend installing Rancher by running a single Docker container.

One difference from the 1.6 version is that Rancher now requires you to use SSL for security, so you need to provide a certificate during installation. If you don’t provide a certificate, Rancher will generate a self-signed certificate for you. For all the certificate options, see here.

Installing a High Availability Rancher setup is a lot different compared to 1.6. The steps are outlined here.

Note that any existing automation that you have around a 1.6 Rancher Server in HA mode will need to be redone for 2.0.

Configure Authentication

If you have set up authentication with Rancher 1.6, you will be familiar with the array of auth providers supported.

With Rancher 2.0, all the above auth providers are still supported, and there are few new ones added to the set as well! Here is what the upcoming v2.0.7 authentication provider line up looks like:

The basic configuration requirements for setting up auth are still the same as 1.6. Look here for detailed documentation about configuring every auth provider.

One difference to highlight is that in the Rancher 2.0 setup, local auth is always turned on, even if you configure any other auth mechanism. This setting enables the Rancher admins to have a guaranteed access to the setup always!

Add a Cluster and a Project

After you have a running Rancher installation with your choice of authentication enabled, the next thing to do is create a Cluster and a Project under which workloads can be deployed.

In the Rancher 1.6 setup, after installation, you would create an environment to which compute nodes could be added. In Rancher 2.0, you need to create a cluster and add the compute nodes to the cluster.

• What is a Cluster?

• How to Create a Cluster in Rancher 2.0?

This is what the Cluster view looks like after it is setup. Within each cluster a Default project will be available.

The equivalent of a 1.6 Cattle environment is a 2.0 cluster with a project, for the following reasons:

• In 1.6 compute resources were assigned to an environment. Here in 2.0, you assign them to a cluster.

• In 1.6 users were added to the environment, where they could deploy services and share access to the hosts that belonged to that environment. In 2.0, users are added to projects and the workloads they deploy have access to the resources granted to the project.

This model of a cluster and a project allows for multi-tenancy because hosts are owned by the cluster, and the cluster can be further divided into multiple projects where users can manage their apps.

Create Namespaces

After adding a cluster and a project, the next step is to define any namespaces used to group your application workloads. In Rancher 1.6, stacks were created to group together the services belonging to your application. In 2.0, you need to create namespaces for the same purpose. A default namespace will be available within the project, which is the namespace where workloads are deployed if one is not explicitly provided.

Just like 1.6, Rancher 2.0 supports service discovery within and across namespaces.

Migrate Apps

Once your Kubernetes cluster and a project are in place, the next step is to migrate the workloads.

• If you are a Rancher 1.6 user using Cattle environments, then you’ll need to understand the changes in Rancher 2.0 around scheduling, load balancing, service discovery, service monitoring, and more while you migrate your workloads.

  You can follow the upcoming blog series that talks about how you can do this migration using either the Rancher 2.0 UI or a conversion from Docker Compose config to Kubernetes YAML. It aims to explore various areas around workload deployment and their equivalent options available in Rancher 2.0.

• If you have been running your workloads in a Rancher 1.6 Kubernetes environment already, you can import the Kubernetes YAML specs directly into a Rancher 2.0 cluster using either the UI or Rancher CLI.

Hope this migration checklist helps you get started!