> From Docker to Kubernetes > Setting up Rancher

Setting up Rancher

TL;DR

In this section, we will:

Install the cockpit web interface
Install updates
Set a dns entry for your server
Install the k3s kubernetes engine
Install cert manager and rancher via a helm CRD

Initial Housekeeping

If you have been following the previous section, we are currently presented with a blinking cursor to log into our new Debian server.

If you are confused about the lack of a graphical login screen, nearly all server distributions of linux are completely command line based. No graphical login at all! This is by design, to increase stability and cut down on overhead.

Luckily for us, debian has another option. Let’s install a robust web management console called cockpit. You can do so (once logged in as root) by running the following in the text console:

apt update
apt install -y cockpit

If all goes well, you can use your web browser to log into the server at https://(your-ip):9090.

you can get the ip address of the server by running ip a within the text console. Note that your IP might change when switching to network manager on DHCP.

Log in with a username of root and the password you designated during installation. With any luck, you should be presented with a dashboard of your new server:

Installing Updates

Well, that’s a lot friendlier than a command line already! Before going any further, let’s press the software updates submenu, and get our server up to date from the initial install.

Setting DNS

As said before, it’s important that we are able to get to our installation via a domain name (as opposed to an IP address).

If I want to route to that server, I’m going to need to put a DNS entry for it somewhere upstream. That can be:

at my computer’s hosts file (ugh, no)
at my router/dns server/pihole (preferred)
at my public DNS provider/Domain Registrar (fine if you’re planning to port forward, but unnecessary).

Given that my router is not your router, this process will vary wildly. Openwrt is about as common a router as you can get so let’s show the process there.

Setting a DNS entry in OpenWRT

Log into your OpenWRT router, and navigate to network→hostnames. add an entry there.

Add an entry for your new server, and set it to your server’s IP address. save, then save & apply.

This dns entry doesn’t necessarily have to match the name you gave your computer (or even the domain), but it’s good to keep the names consistent.

Installing K3S Pre-requisites

Hold on, what’s k3s? I thought this was a guide about kubernetes? Well, Kubernetes is a container orchestrator made by google, also known as k8s. However, k8s was designed with many moving parts for a distributed datacenter. We have a single machine.

Rancher (the company) makes a competing, lightweight engine called K3S. As the name implies, it’s an alternative to kubernetes; fully compatible with the k8s API. Rancher (the company) also makes Rancher (the web management platform) for managing kubernetes through a web interface. Perfect for our needs!

Installing pre-requisites

First we need to install the pre-requisites. You can do so by navigating to the terminal tab in cockpit and running the following:

apt install -y open-iscsi containerd apparmor apparmor-utils nfs-common

you can paste into the cockpit terminal with control+shift+v, or shift+insert

Reboot

Go ahead and reboot one more time in the terminal to clean up everything we’ve done

reboot now

Installing K3S

K3S is quite easy to install (as long as you don’t mind executing code directly from Rancher’s website):

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--no-deploy traefik" sh -s -

We do not install the default traefik ingress controller because traefik 2 is clunky and unintuitive to use. We will install the nginx ingress controller later instead.

You can check when it’s done by running:

kubectl describe all

Once you have that, you’re looking good!

Installing Nginx-Ingress, Cert-Manager, and Rancher

Now K3s by its lonesome will not provide us with a full rancher web management experience. We still need to bootstrap rancher, inside K3S. We do this by planting some formatted yaml files inside k3s, which tells k3s to set up the components we need (nginx-ingress, cert-manager, and rancher). These files are referred to as helm chart CRDs.

I’ve gone to the liberty of creating a shell script to install that for you. Paste the following into the cockpit terminal and set your rancher hostname when prompted.

#!/bin/bash

#set our rancher hostname 
rancherHostName=
hostNameChoice=n
domainRegex='(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?.)+[a-z0-9][a-z0-9-]{0,61}[a-z0-9]'
while [ "$hostNameChoice" != "y" ]
do
    echo 'set your rancher hostname (IE: kub01.myDomain.com.au)'
    read rancherHostName
    echo "you set your rancherHostName to $rancherHostName"
    read -p "Is this right (y/n)? " hostNameChoice
    printf "\n"
done

if echo "$rancherHostName" | grep -q -v -P $domainRegex
then
  echo "$rancherHostName does not match a normal domain name"
  exit
fi

#create the namespaces we need
kubectl create namespace ingress-nginx
kubectl create namespace cert-manager
kubectl create namespace cattle-system

#create a label for cert manager
kubectl label namespace cert-manager certmanager.k8s.io/disable-validation=true

#Install Nginx Ingress
cat > /var/lib/rancher/k3s/server/manifests/ingress-nginx.yaml <<EOF
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: ingress-nginx
  namespace: kube-system
spec:
  chart: ingress-nginx
  repo: https://kubernetes.github.io/ingress-nginx
  targetNamespace: ingress-nginx
  set:
  valuesContent: |-
    fullnameOverride: ingress-nginx
    ingressClassResource:
        default: true
    controller:
      watchIngressWithoutClass: true
      kind: DaemonSet
      hostNetwork: true
      hostPort:
        enabled: true
      service:
        enabled: false
      publishService:
        enabled: false
      metrics:
        enabled: true
        serviceMonitor:
          enabled: true
      config:
        use-forwarded-headers: "true"
EOF

#Install Cert-Manager
cat > /var/lib/rancher/k3s/server/manifests/cert-manager.yaml <<EOF
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: cert-manager
  namespace: cert-manager
spec:
  repo: https://charts.jetstack.io
  chart: cert-manager
  targetNamespace: cert-manager
  valuesContent: |
    installCRDs: true
EOF

#Install Rancher
cat > /var/lib/rancher/k3s/server/manifests/rancher.yaml <<EOF
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: rancher
  namespace: cattle-system
spec:
  repo: https://releases.rancher.com/server-charts/latest
  chart: rancher
  targetNamespace: cattle-system
  valuesContent: |
    replicas: 1
    hostname: $rancherHostName
EOF

Checking the Install Status

It will take a couple minutes for all that stuff to apply. You can check on the status by running the following:

kubectl get pods --all-namespaces | grep helm

It’s fine for the installs to error out (some of the installs depend on the others). K3s will automatically retry until they succeed

Once you get a completed status for everything, you’re good to go!

Logging into Rancher

Navigate to your server at https://<yourserver>.<yourdomain>. If all’s gone well, you should be prompted with a login screen:

If you tried using an IP address at this stage, as opposed to a DNS name, you will not be routed correctly and cannot log into rancher.

Copy the code for the helm installation and paste in your terminal. You should get a unique one-time password to use:

At the home screen, set the take me to cluster: local option and navigate to your local cluster.

Congratulations! You just installed a single node k3s deployment with the rancher web management interface.

Next Steps

We’ve now successfully installed and configured our cluster in the rancher web interface. Next step is to actually create a working kubernetes container with hello world and caddy!