K3s on the Raspberry Pi 4
Setting up my media, backup, and game servers from scratch in 4 minutes
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.
With the Pi in hand, lets get started!
Prepare an SD Card
NOTE: We strongly recommend using a Pi that is compatible with 64-bit Raspberry Pi OS. If you don't have a pi handy, you can order a PiBox from us at https://pibox.io
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 networktouch /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 create -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.
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.
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.
If your deployment shows0/1underREADY, you can troubleshoot it usingkubectl 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 Discord support room!
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.
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!
Join our Discord server, give us a shout on twitter, check out some of our GitHub repos and be sure to join our mailing list!
