K3s on the Raspberry Pi 4

Setting up my media, backup, and game servers from scratch in 4 minutes

Dan Pastusek
Jun 19, 2020

NOTE this guide is nearly identical to the MicroK8s Raspberry Pi article, but adapted to use K3s instead. Both MicroK8s and K3s are easy-to-install, lightweight alternatives to running the full Kubernetes software stack. MicroK8s is maintained by Canonical, while K3s is maintained by Rancher Labs.

When the Raspberry Pi 4 was announced last summer, I was shocked at the specs. It packs a 1.5GHz processor, Gigabit ethernet, USB 3.0 ports, and up to 4GB RAM. After getting my hands on one, I had to see if I could replace my old NUC home server with this significantly cheaper and more efficient computer. While I was at it, I figured this was a good time to try out Kubernetes, and use KubeSail to version and template my configurations, so the next time I upgrade my apps, setup would just be a few clicks.

Pi + HDD

With the Pi in hand, lets get started!

Prepare an SD Card

Flashing the Pi

There are multiple ways to get an operating system on your SD card, but the easiest is to download the Raspberry Pi Imager to your computer, select Raspberry Pi OS Lite, and hit "write". This process will take about 5 minutes. ☕

Before removing the SD card from your computer, place an empty file in the root of the drive called ssh. This will enable the SSH server so you can login to the Pi from your network

touch /Volumes/boot/ssh

NOTE: If you are connecting your Pi via Ethernet, you can now insert the SD card into the Pi, power it on, and skip the WiFi section. Otherwise don't remove your SD card from your computer yet!

Setting up WiFi

If you plan to connect your pi via Wi-Fi, you'll want to configure these network details on the SD card before you power on your Pi. Create a file called wpa_supplicant.conf on the root of the drive. Add your network's SSID and password to the network section and save the file.

At the end that file should look something like this, assuming your network is named My WiFi Network:

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="NETWORK-NAME"
    psk="NETWORK-PASSWORD"
}

You can now take your SD card out, insert into the Pi, and power it on.

Log in to the Pi

The Pi should register its hostname with your router, so you'll likely be able to

ssh ubuntu@ubuntu

If that fails with an error like Could not resolve hostname ubuntu then you'll need to log into your router and find the IP of your Pi. In that case, you'll login via ssh pi@<YOUR_PI_IP_ADDRESS>

The initial password is raspberry. You will likely want to change it on first login by running passwd to keep out others on your network. There are multiple ways to install K3s, but the simplest is via the installation script:

curl -sfL https://get.k3s.io | sh -

Once the Pi reboots, we'll need to ssh back into the machine. Once we're in, let's see which machines are in our cluster by running

sudo k3s kubectl get nodes

This may take a minute while the pi starts up all the software that powers Kubernetes. Eventually you should see

NAME          STATUS   ROLES    AGE   VERSION
raspberrypi   Ready    master   2m    v1.18.4+k3s1

Yay! We now have one node in our cluster (the Raspberry Pi itself). We could add more machines in the future, but for now we will run this as a single-node cluster. A Ready status means that Kubernetes is up and running, ready to deploy any software we want!

Connect KubeSail

This step makes it much easier to manage the configurations in the next steps. If you haven't already signed up for KubeSail, do that now. Its free and just requires a GitHub account to register. Then, to manage your raspberry pi from the KubeSail dashboard, just run

sudo k3s kubectl apply -f https://byoc.kubesail.com/$YOUR_KUBESAIL_USERNAME.yaml

Your Pi will appear as a new cluster for you to manage in the KubeSail Cluster Dashboard.

Adding a Cluster

Once you have verified your cluster, you can manage all the software running on your Rapsberry Pi using the KubeSail dashboard.

Deploy software

Finally to the fun stuff! Lets start by deploying an rTorrent Docker image.

At this point, most tutorials will give you some YAML files to apply to your cluster. But in our case, we're going to use KubeSail to apply the rTorrent template directly to your cluster. Templates let you see the resources that will be created in the UI (or as YAML), and gives you the flexibility to fork and edit them before applying.

rTorrent Template

Once you've applied the template to your cluster, you can run

sudo k3s kubectl get deployments,services

and output should look like this:

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/rutorrent   1/1     1            1           28m

NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                                       AGE
service/kubernetes   ClusterIP   10.152.183.1     <none>        443/TCP                                       3h30m
service/rutorrent    NodePort    10.152.183.206   <none>        80:30001/TCP,5000:30002/TCP,51413:30003/TCP   28m

Note the port mapping If you navigate to http://ubuntu:30001 you should see the rutorrent dashboard running! Remember that ubuntu may not work as a hostname depending on your router. If this is the case, replace it with the local IP of your Raspberry Pi.

Pi + HDD

If your deployment shows 0/1 under READY, you can troubleshoot it using kubectl describe deployment/rutorrent. Most likely, Kubernetes is taking a while to download the large Docker image.

Access from the Internet

If you want to access your rTorrent dashboard from the internet, KubeSail allows you to expose HTTP services, on any domain name, even behind your firewall. However, before you do that you may want to secure your dashboard with a username / password. For now, we'll leave this exercise up to the reader, but if you'd like a Part II article showing how that can be achieved on Kubernetes, drop us a line in our Gitter support room!

Pi + HDD

Browse more templates

KubeSail has a growing library of public templates which can be created by you or anyone in the community. Head over to the Template Registry to browse public templates. Everything you'd want to self-host, from Plex Server to Postgres, can be found there.

Template Registry Screenshot

Publish your templates

If you have software you self-host, consider sharing it with the community by copying your Kubernetes configs into a new template and clicking the "Save Template" button.

Stay in the loop!

Give us a shout on twitter or gitter, check out some of our GitHub repos and be sure to join our mailing list!