Introducing Rancher

Rancher Banner Rancher is a single platform for managing Kubernetes clusters, built by the folks behind k3s, the lightweight Kubernetes distribution. Designed to simplify Kubernetes management wherever your clusters are running, and to allow you to determine a configuration for new clusters, it is a powerful tool that is well worth getting to grips with. Once your clusters are running, Rancher helps administrators by simplifying their responsibilities, from global security policies to a centralised log system. Not only that, it also allows users to deploy work loads and configure services such as load balancing and persistent volume claims.

This guide will run through installing Rancher from the Civo Kubernetes App Marketplace, along with basic Rancher usage. Once you have your cluster up and Rancher deployed with the steps shown below, head over to the official Rancher documentation to learn more.

Our Kubernetes App Marketplace is open source! Rancher was submitted by Civo community member Saiyam Pathak - we're very thankful for our community for their contributions. If there is a Kubernetes application you would like to contribute, head over to the marketplace to add it.

Note: Software changes over time. All instructions below work at the time of writing and publishing, so if you follow along and find that something does not work like in the examples below, let us know and we will update the guide.


To follow along with this guide, you will need to have a Civo account with Kubernetes access enabled and You can sign up here. Successful applicants will receive $70 free credit monthly for the duration of the Beta testing period, in return for their feedback and contributions.

You will also need to have kubectl installed from the official source, and a basic understanding of command-line interfaces. I am using a Mac so my screenshots will reflect this, but any terminal emulator will work.

I would also recommend you get kubectx to allow you to switch between cluster contexts.

Using Civo's App Marketplace

Civo's App Marketplace simplifies the installation and deployment of Kubernetes applications onto your cluster. We will be using the Civo web interface to create an initial Kubernetes cluster and add Rancher to it at initialisation, allowing us to be up and running quickly.

Creating your cluster

Navigate over to the Kubernetes control panel in your account, and click on Create cluster. You should be presented with a view for creating a new cluster as in the screenshot below.

New Cluster Creation

Go ahead and pick the following options, and give your cluster the name of your choice:

  • Number of nodes: 3
  • Size: Medium

Then, scroll down to the Marketplace section, and under Management find and select Rancher, and hit the Create button:

Rancher Marketplace App

Within a few minutes, you should have a cluster ready to go! As the Master node does work in k3s clusters, as soon as one node has been designated master, your cluster will be usable.

Applying the Rancher configuration

The next step will be to enable access to the Rancher application itself. Please note that by default, the following instructions will allow access from the whole world. You should take all necessary steps to secure access to your cluster.

To enable access, scroll down to the "Installed applications" section of your cluster control panel, and click on the Rancher tab to expand it:

Rancher Instructions

As you can see, we're going to need to apply a short configuration file to your cluster using kubectl. For that, we'll need to download the cluster's kubeconfig file and save (or merge) it to your ~/.kube/config file. You can download the configuration file from the top part of the cluster panel:

Download Kubeconfig

If you don't have another cluster configuration file, it's as simple as copying the downloaded file into ~/.kube/config or any other location you may have configured kubectl to look in.

If you do have another cluster configuration file that you want to keep around, you would need to merge the configuration according to the instructions here, and then switch to the new context using kubectx or the kubectl config use-context command, or use KUBECONFIG=~/Downloads/civo-your-cluster-kubeconfig before every command

Now that we have our cluster configuration saved and the context set, it's time to apply the configuration to allow access to Rancher.

Open up a text editor and paste in the "External access" configuration yaml file, saving it as rancher-ingress.yaml.

Rancher-ingress yaml

Now, let's apply the file into our cluster! Run this command in the directory where you saved rancher-ingress.yaml:

$ kubectl apply -f rancher-ingress.yaml

ingress.extensions/cattle-ingress created

Accessing Rancher

On the cluster information page, you should be able to see the IP address for the master node of your cluster. Enter this IP address (or the DNS name of the cluster) to your browser bar and you should see the initial setup page for Rancher:

Rancher Welcome Page

Set up a secure password and accept the default URL for the service, and you will be presented with the main Rancher screen. that allows you to click on the local cluster link to see the status of our first cluster. It should look a little something like the below, after a few minutes of self-configuring:

Rancher Local Dashboard

Strictly speaking, this is all you need to do on the Civo platform to get up and running with Rancher by installing it from the app marketplace. The next section will cover the use case of adding another Civo-hosted cluster to Rancher for monitoring and management.

Adding another cluster to Rancher

Rancher allows you to manage clusters from a variety of providers, making sure that settings are uniform and status is monitored no matter where the cluster is physically hosted. Next, we are going to add another Civo cluster to be monitored and managed through our existing Rancher installation.

Head back to your Civo account and start up another cluster with a name and size settings of your choice - this is not for any particular work load so the particulars don't matter too much.

New Cluster Creation

Once this new cluster is running, we will need to download its kubeconfig and get it merged before we switch to the new cluster to attach it to our Rancher app. As before, you will find the option to download this file in the top part of a running cluster's control page, or alternatively, if you are using the Civo CLI, you can simply run:

civo kubernetes config your-cluster-name --save

which will correctly merge the configuration file alongside the original cluster configurations.

Next, we will need to switch to our new cluster's context to apply a configuration to it. The easiest way to do this is using kubectx which is why I recommended above you get it installed.

$ kubectx your-new-cluster-name
Switched to context "your-new-cluster-name".

Now, we will get the requisite configuration information from our Rancher setup to apply to our new cluster to get it added. These instructions are taken from the official Rancher documentation, but reproduced for your convenience here.

  1. On the Clusters page of the Rancher UI, click Add Cluster and choose Import an existing cluster as the type.

  2. For the name of the cluster, enter what you chose when you created the cluster on Civo.

  3. Click Create to get Rancher to output a command that you can run on your local machine using kubectl. It will be specific to your cluster, but will look something like this:

Rancher import command

  1. Make sure you have set your context correctly (instructions above) and paste the resulting command into your terminal, letting kubectl apply the configuration to the cluster.

  2. Click Done on the Rancher UI and allow a few minutes for the resources to be deployed to your new cluster. It will show as Active when this process is complete.

You should see the second cluster in your management screen now, allowing you to set configurations across your installation at will.


If you followed this guide, you will have successfully deployed Rancher from the Kubernetes marketplace to manage your Kubernetes clusters on Civo. You will have logged in to this Rancher service, and then imported another Civo cluster as a demonstration of Rancher functionality.

Remember that this guide is only a quick demonstration of how to deploy Rancher with the intention of showing you the ins and outs of using applications from the Marketplace. You should definitely secure the cluster with SSL and create the appropriate user roles in the Rancher app itself if you were deploying it to manage any kind of cluster beyond one such as the above you are testing things out on.

If deploying applications like this to a Kubernetes cluster appeals to you, join Civo's managed Kubernetes service to get going! And, if you have any comments about this guide, whether you found it useful or insightful or whatever, give me a shout on Twitter at @kaipmdh and Civo @civocloud.