Setting Up a K3S Cluster on Alpine Linux with Raspberry Pi 5 Using a Mac

7 min readFeb 4, 2024

Welcome, in this article, I’ll guide you through the process of installing Alpine Linux on a Raspberry Pi 5 and setting up a K3S cluster. With the release of Alpine Linux 3.15, official support for Raspberry Pi 5 is now available, allowing for a seamless installation of this lightweight OS.

Setting Up a K3S Cluster on Alpine Linux with Raspberry Pi 5 Using a Mac

Prerequisites
- Raspberry Pi 5: 4GB or higher recommended; a minimum of two Raspberry Pi 5 units is required for cluster setup.
- SD Card: Minimum of 16GB.
- A PC with an SD card reader.
- Internet connection.
- Ethernet cable for a wired connection.

Step 1: Download Alpine Linux

First, download the Alpine Linux image. Navigate to Alpine Linux Downloads and select one of the aarch64 options.

Step 2: Prepare for Headless Setup

If you’re opting for a headless setup (i.e., without a monitor, keyboard, or mouse, using SSH instead), download the headless.apkovl.tar.gz file from GitHub — Alpine Linux Headless Bootstrap.

Step 3: Extract Alpine Linux Image

Extract the downloaded Alpine Linux image to a folder and copy the headless.apkovl.tar.gz file into this folder for a headless installation.

Step 4: Prepare the SD Card

Insert the SD card into your computer.
Open the terminal and execute diskutil list to identify the SD card’s device path (e.g., /dev/disk4).

Carefully format the SD card to avoid data loss:

diskutil eraseDisk free EMPTY /dev/disk4

Partition the SD card:

diskutil partitionDisk /dev/disk4 2 MBR fat32 ALPINE_BOOT 512M free ALPINE R

Step 5: Copy Alpine Linux Files

Copy the previously prepared Alpine Linux image files to the SD card using the command:

cp -r [alpine_image_files_folder]/. /Volumes/ALPINE_BOOT

Step 6: Raspberry Pi 5 Setup

Remove the SD card from your computer and insert it into the Raspberry Pi 5.
Connect the Raspberry Pi 5 to your network with an Ethernet cable.
Power on the Raspberry Pi 5 and find its IP address from your router’s interface. (e.g. 192.168.68.56)

SSH into the Raspberry Pi 5 using its IP address: ssh root@[raspberry_pi_5_ip_address]. No password is required initially; press enter when prompted.

Step 7: Installation

Begin the installation by running `setup-alpine`. Follow the prompts to configure your setup. Here are the responses I used for certain prompts, adjust as necessary for your environment: (You may answer default responses for other questions)

Hostname: `raspberry-4`
IP address for eth0: `192.168.68.104`
Root Password: `123456` 
Timezone: `Turkey`

APK Mirror: Choose the fastest mirror by selecting `[f]`.
Setup a user?: `no` (we will use the default root user).
Allow root ssh login?: `yes`

Step 8: Enable Running from SD Card

Execute the following commands to enable the Alpine community repository, update the system, and install necessary packages:

sed -i 's/#\(.*\/community\)/\1/' /etc/apk/repositories
apk update
apk upgrade
apk add cfdisk e2fsprogs lsblk vim curl sudo vim htop raspberrypi-utils-pinctrl

Step 9: SSH Setup

To ensure SSH starts correctly on reboot, execute:

rc-service sshd restart
rc-update add sshd

Step 10: Disk Configuration

In this step, we’ll manage the disk partitions on the SD card. Recall that earlier in the setup, we divided the SD card into two parts: the first for the boot partition, and the second, designated as mmcblk0p2, for the system partition. We initially booted from the first partition. Now, we will focus on setting up the second partition, mmcblk0p2, for system use.

Begin by launching the partition manager with the command cfdisk /dev/mmcblk0. This utility allows you to view and modify disk partitions. You should see the second partition you previously created, which is currently unallocated space.

cfdisk /dev/mmcblk0

Use the arrow keys to navigate to the Free space selection. Then, press the Tab key to move to the options below and choose New to create a new partition in this unallocated space.

Confirm your choice by pressing Enter. When prompted, select the partition type as Primary and confirm again with Enter. You will then return to the main screen, where you’ll see a new partition has been created within your disk layout.
Next, select Write to save the changes to the disk. You’ll be prompted to confirm; type yes and press Enter. This action commits your partition changes.
After saving, you might want to make the partition bootable, although this is typically not necessary for the second partition in this context. However, if needed, select the Bootable option and confirm with Write again by typing yes and hitting Enter.
To exit cfdisk, choose Quit and press Enter.
Verify the new partition structure by using the lsblk command. You should see the mmcblk0p2 partition listed, indicating that it has been successfully created.

The final step involves formatting the new partition with an ext4 filesystem and mounting it. This prepares the partition for storing the system files. Execute the following commands to format and mount the partition:

mkfs.ext4 /dev/mmcblk0p2
mount /dev/mmcblk0p2 /mnt

These commands will format the mmcblk0p2 partition with an ext4 filesystem, which is a reliable and widely used filesystem for Linux systems, and then mount it to /mnt. This action makes the partition accessible for use, allowing you to proceed with copying system files in the next steps of the installation process.

By completing these steps, you’ve effectively prepared your SD card’s system partition, setting the foundation for the Alpine Linux installation and further configurations on your Raspberry Pi 5.

Step 11: Copy System Files

Copy the system files to the SD card for booting directly from it on subsequent reboots:

setup-disk -m sys /mnt -o /media/mmcblk0p1/alpine-headless.apkovl.tar.gz

Update the first partition to ensure the system can boot from the SD card after a reboot:

mount -o remount,rw /media/mmcblk0p1
rm -f /media/mmcblk0p1/* # Ignore `is a directory` errors
rm -rf /media/mmcblk0p1/overlays

cd /mnt # Navigate to the mounted directory
rm boot/boot
mv boot/* /media/mmcblk0p1/
rm -Rf boot
mkdir media/mmcblk0p1 # Create a directory for linking
ln -s media/mmcblk0p1 boot # Create a symlink for boot volume access
echo "/dev/mmcblk0p1 /media/mmcblk0p1 vfat defaults 0 0" >> etc/fstab

After executing these steps, you can reboot your system with the command. From this point forward, your system will boot from the SD card, and you should be able to SSH into the device using the network IP (192.168.68.104) and root password set earlier.

Step 12: System Configuration and K3S Installation

To ensure your system is up to date and configured to automatically start essential services, follow these steps:

Update the system and install Docker:

sudo apk update
sudo apk add docker
sudo addgroup root docker
sudo rc-update add docker default
sudo service docker start

Modify the `cmdline.txt` file to include necessary `cgroup` settings for K3S installation:

sudo sed -i '$ s/$/ cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 swapaccount=1/' /boot/cmdline.txt

Reboot the system to apply these settings with reboot command

Upon restarting, you can proceed with the K3S installation:

For setting up a master node, use the following command:

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

When adding a worker node to an existing master node, you will need the master node’s IP address and token. The master node’s IP address ([master_node_ip]) is the IP address of the first node where K3S was installed. You can obtain the master node’s token, which is required for joining a worker node to the cluster, with the following command on the master node:

cat /var/lib/rancher/k3s/server/node-token

To add a worker node to the cluster, replace [master_node_ip] with the master node’s IP address and [master_node_token] with the token obtained from the master node. Then, execute:

curl -sfL https://get.k3s.io | K3S_URL=https://[master_node_ip]:6443 K3S_TOKEN=[master_node_token] sh -

This setup completes the addition of a worker node to your K3S cluster. To verify and manage services on Alpine Linux, use rc-status command:

K3s installed for worker node and checked with rc-status command.

Congratulations, your K3S cluster on Alpine Linux using Raspberry Pi 5 is now ready. This guide has covered the necessary steps to install and configure your system for both a standalone setup and as part of a scalable, lightweight Kubernetes cluster.

Keep in Touch

I hope you found this guide helpful and informative. If you have any questions, comments, or would like to discuss further the topics covered in this article, please feel free to reach out.

You can contact me via:

Email: nedmylmz@gmail.com
LinkedIn: #nedimyilmaz

I’m always open to feedback, suggestions, and engaging in discussions about technology, programming, and innovation. Don’t hesitate to connect!