K3s is a lightweight Kubernetes distribution ideal for edge, IoT, and development environments. Alpine Linux is a minimal OS, so a few extra steps are required to prepare it for K3s.

This guide walks through setting up a basic K3s cluster on Alpine Linux (OpenRC init system).

Setup Hosts Prerequisites

If you’re starting from a minimal Alpine install, install essential tools:

apk add --no-cache curl git bash

Install cni-plugins and iptables:

apk add --no-cache cni-plugins --repository=http://dl-cdn.alpinelinux.org/alpine/edge/testing  
apk add iptables

# Optional: Add to PATH if needed
export PATH=/usr/share/cni-plugins/bin:$PATH

Modify the line in /etc/fstab to use cgroup. Note: in my experience I didnt not need to enable cgroup v2

  echo "cgroup_enable=memory systemd.unified_cgroup_hierarchy=0" >> /etc/fstab

Inspect the updatedfstab config:

  cat /etc/fstab

  UUID=e70fc0c1-0a5f-4746-a79e-8235a86f6d80       /       ext4    rw,relatime 0 1
  UUID=c2ce53b2-8f43-4fe5-aaa6-73cb7318277e       /boot   ext4    rw,relatime 0 2
  UUID=280cd4a7-48f5-40e2-a5e9-ab004e06af18       swap    swap    defaults        0 0
  /dev/cdrom      /media/cdrom    iso9660 noauto,ro 0 0
  /dev/usbdisk    /media/usb      vfat    noauto  0 0
  tmpfs   /tmp    tmpfs   nosuid,nodev    0       0
  # added cgroup config below
  cgroup_enable=memory systemd.unified_cgroup_hierarchy=0

No reboot needed at this stage unless explicitly required by your boot setup.
Configure control group mounts

Alpine Linux utilizes openrc, a dependency-based init system, as its primary process during boot instead of the traditional system on other Unix-like systems.

Let’s now make changes to the cgconfig.conf file. This configuration file, utilized by libcgroup, defines control groups, their parameters, and mount points. The file comprises two sections: mount and group. These sections can be arranged in any order.

cat > /etc/cgconfig.conf <<EOF
mount {
  cpuacct = /cgroup/cpuacct;
  memory = /cgroup/memory;
  devices = /cgroup/devices;
  freezer = /cgroup/freezer;
  net_cls = /cgroup/net_cls;
  blkio = /cgroup/blkio;
  cpuset = /cgroup/cpuset;
  cpu = /cgroup/cpu;
}
EOF

Some older guides suggest modifying /etc/update-extlinux.conf. In my experience (as of 2025), this step is not necessary on most Alpine versions unless cgroups are not mounting properly.

  sed -i 's/default_kernel_opts="pax_nouderef quiet rootfstype=ext4"/default_kernel_opts="pax_nouderef quiet rootfstype=ext4 cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory"/g' /etc/update-extlinux.conf

  update-extlinux
  reboot

Install k3s

Now that our Alpine host is ready, we can proceed with the K3s installation. Depending on your desired setup, there are several installation flags that you can customize to turn add-on services on or off.

To install Cilium, you must set up your k3s cluster as usual. However, disabling the default CNI plugin and the built-in network policy enforcer is essential to make the installation of Cilium possible.

You can check that you have resolved any Additional OS Preparation. Run the command below and ensure every check has passed:

  k3s check config

Install K3s with the flags to make sure /etc/rancher/k3s/k3s.yaml is world-readable and service loadBalancer, Klipper, and traefik are disabled, and for Cilium, flannel-backend=none

sudo -i

export K3S_KUBECONFIG_MODE="644"
export INSTALL_K3S_EXEC=" --flannel-backend=none --disable-network-policy --disable servicelb --disable traefik" 

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

This disables the default CNI (Flannel) and other built-ins to prep for installing Cilium later.

Example output

[INFO]  Finding release for channel stable
[INFO]  Using v1.28.4+k3s2 as release
[INFO]  Downloading hash https://github.com/k3s-io/k3s/releases/download/v1.28.4+k3s2/sha256sum-amd64.txt
[INFO]  Downloading binary https://github.com/k3s-io/k3s/releases/download/v1.28.4+k3s2/k3s
[INFO]  Verifying binary download
[INFO]  Installing k3s to /usr/local/bin/k3s
[INFO]  Skipping installation of SELinux RPM
[INFO]  Creating /usr/local/bin/kubectl symlink to k3s
[INFO]  Creating /usr/local/bin/crictl symlink to k3s
[INFO]  Creating /usr/local/bin/ctr symlink to k3s
[INFO]  Creating killall script /usr/local/bin/k3s-killall.sh
[INFO]  Creating uninstall script /usr/local/bin/k3s-uninstall.sh
[INFO]  env: Creating environment file /etc/rancher/k3s/k3s.env
[INFO]  openrc: Creating service file /etc/init.d/k3s
[INFO]  openrc: Enabling k3s service for default runlevel
[INFO]  openrc: Starting k3s
 * Caching service dependencies ...                                                                                                                                                        [ ok ]
 * Starting k3s ...                                     

If you encounter any errors, check logs to inspect errors:

  sudo journalctl -u k3s.service

Connect to your K3s Kubernetes Config on the Master node

To use kubectl, copy the K3s config file:

mkdir -p ~/.kube
cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
kubectl get nodes

See the available nodes

kubectl get nodes

NAME                STATUS     ROLES                  AGE     VERSION
k3s.pve.armand.nz   NotReady   control-plane,master   54s     v1.28.4+k3s2

Install Metric Server

A useful tool to have is metric-server, as the first install is a good way to confirm your k3s cluster is operational too.

helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
helm repo update
helm upgrade --install metrics-server metrics-server/metrics-server

Install Cilium

You can follow my other notes on installing Cilium. The only difference would be installing helm first on Alpine is done using apk, i.e. apk add helm

Armand.nz

Install k3s on Alpine Linux

Setup Hosts Prerequisites

Install k3s

Connect to your K3s Kubernetes Config on the Master node

Install Metric Server

Install Cilium