This is a quick tutorial on how to get your own Kubernetes cluster up and running in no time. This is basically the procedure I use every time I want to add a new cluster or when I have to rebuild one for any reason.

If you already have a Linux machine setup, you may jump to “3. K3S installation”

First, TLDR

# 1. Install Debian / Raspbian

# 2. Setup cgroup thingy if this is a Pi
sudo nano /boot/cmdline.txt
# Add cgroup_memory=1 cgroup_enable=memory

# 3. # Download and install K3S
curl -sfL https://get.k3s.io --output get-k3s.sh
chmod +x get-k3s.sh
./get-k3s.sh --disable=traefik

# 4. Install Lens: https://github.com/MuhammedKalkan/OpenLens/releases

# 5. Connect with Lens or any other client, using the credentials and replacing 127.0.0.1 by your IP address
sudo ip a # To find your IP
sudo cat /etc/rancher/k3s/k3s.yaml # To retrieve default admin credentials

1. Go get yourself a Pi

First, you should choose some hardware for your cluster. I personally started with a Raspberry Pi as they are were pretty inexpensive little machines. You can really use any device, though the steps might vary slightly.

In this tutorial I will cover the Raspberry Pi 4B. I would advise you choose the 4GB or 8GB models to host your services, but this should work with older models or with less memory. You’ll also need a USB power supply and a MicroSD, usual things with the Pi.

I will also cover a generic x64 platform matching my current setup at home, with my Mele Quieter 3Q. But any old computer would do the trick as well!

2. Basic setup

If you have a Raspberry Pi

1. Download the Raspberry Pi Imager available here: https://www.raspberrypi.com/software/
2. Use it to install “Raspberry Pi OS (32-bit)”. The 64-bit might work, but I did not test it
3. Boot your Pi, and get access to the shell either physically with a keyboard or using SSH
4. You’ll need to enable cgroup (https://github.com/rancher/k3s/issues/170)
   • sudo nano /boot/cmdline.txt
   • Add the command line parameters below in the command line
     cgroup_memory=1 cgroup_enable=memory

   Your command line should look similar to:

   console=tty1 root=PARTUUID=266982c5-02 rootfstype=ext4 elevator=deadline fsck.repair=yes rootwait cgroup_memory=1 cgroup_enable=memory
   

5. Reboot your Pi

For the generic x64 device

1. Download a Debian ISO from their website: https://www.debian.org
2. Use Rufus (https://rufus.ie/en/) to create a bootable USB with Debian ISO
3. Boot the PC from the USB drive
4. Try to keep your device connected to internet using Ethernet moving forward as it will automatically install the drivers you need
5. Install Debian with the default settings (single partition, install the updates, …)
6. Get access to the shell either physically with a keyboard or using SSH

3. K3S installation

Basic installation

Now the good part, let’s install Kubernetes. I tried multiple distributions, but I find K3S to be the easiest to setup and use.

1. Download the K3S installer: curl -sfL https://get.k3s.io --output get-k3s.sh
2. Make it executable: chmod +x get-k3s.sh
3. Install K3S: ./get-k3s.sh --disable=traefik

At this point, your cluster is installed, up and running. Yes, that simple.

I use the --disable=traefik command line parameter because I handle my own reverse proxy installation. Traefik is a reverse proxy to allow incoming HTTP/HTTPS traffic to reach your services running in the cluster. You can use the built-in one removing this parameter, or read my next articles to understand my setup 🙂

Additional options

All additional options can be found on K3S website: https://rancher.com/docs/k3s/latest/en/quick-start/

But here are the ones I use the most:

• If you ever want a specific Kubernetes version, you can use the command line below. Kubernetes versions list can be found there: https://github.com/k3s-io/k3s/releases

  INSTALL_K3S_VERSION=v1.21.5+k3s2 ./get-k3s.sh --disable=traefik
  

• If you changed your local IP address, you’ll need to run this command line to regenerate the certificates used to connect from your Kubernetes client:

  ./get-k3s.sh --disable=traefik --tls-san 192.168.1.2
  

4. Connection from Lens

Install Lens

Then you’ll need to interact with your cluster. If you live only by CLI, first reconsider using graphical tools, it can help you learn Kubernetes faster, but you can use the official command line tool kubectl (have fun pronouncing this one, I personally say “CubeControl”).

You can download kubectl here: https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/

Else, I would strongly suggest using a graphical tool to help you understand Kubernetes concepts faster and navigating your cluster more easily. If find that Lens is the perfect tool for that: https://k8slens.dev

It is open source, but as the time of writing this article, they recently made it so you have to create a cloud account to use the software. Fortunately, since the software is open source, some people rebuilt it as OpenLens without those limitations: https://github.com/MuhammedKalkan/OpenLens

As they are basically the same, I will refer to both as Lens, even if I personally use OpenLens.

Retrieve your cluster credentials

On the machine with K3S installed, run this command line to retrieve the default admin credentials:

sudo cat /etc/rancher/k3s/k3s.yaml

You now have to add those credentials to Lens or kubectl.

• For Lens, just click the “Add cluster” (located somewhere, I’m sure this will change by the time your read this article so just look for it!), and paste the content of the k3s.yaml file, replacing the 127.0.0.1 reference by the LAN IP of your machine, for example 192.168.1.134
• If you want to use kubectl, merge this configuration with the content of the file %USERPROFILE%\.kube\config, or create the file and put the content of k3s.yaml in it.

Anyway, make sure to replace the 127.0.0.1 reference by the LAN IP address of the machine running K3S.

Connect to your cluster

At this point, either by running kubectl command or by clicking on your cluster in Lens, you should be able to explore your brand new empty cluster!

Now that this - not so big - step is behind us, the following articles will focus on what to install in your cluster.

Tips and tricks

If you want to play with Kubernetes on your computer

Many will cite Minikube, I personally find it overrated and complex to use. Rancher, developer of K3S, recently released Rancher Desktop: https://rancherdesktop.io

It is targeted as a drop-in replacement for Docker Desktop, with built-in container management (Docker and alternative CLIs) and a Kubernetes cluster (it uses K3S).

Just install it, and you’re good to go with your cluster!

What if I want to have a multi-node cluster?

K3S got you covered, once KS is installed on your master node:

1. Retrieve your node token: cat /var/lib/rancher/k3s/server/node-token
2. Install K3S on your second node with this CLI:

   K3S_URL=https://:6443 K3S_TOKEN= ./get-k3s.sh --disable=traefik
   

3. Connect to your master using Lens or kubectl, and the second node will be visible!