Skip to content

Installing a single node K3s Kubernetes distribution

Introduction

K3s is a lighter variant of Kubernetes distribution than RKE2, which was discussed in previous posts. It is well-suited for single node homelab environments or IoT deployments where resource efficiency is important. Based on my testing, K3s consumed less CPU in an idle state than RKE2. In this blog post I will show how to install K3s.

OS used: Debian 12
Software used: K3s 1.30.5

Source

K3s installation

This post will demonstrate how to install K3s Kubernetes distribution as a single node cluster.

In the beginning create new virtual machine for example using tutorial Debian VM fast initialization using Ansible.

K3s storage requirements

Resize your K3s virtual machine disk to have enough free space for images and containers.

IP address requirements

Kubernetes can stop working if you change IP address of a node, so set static IP for your virtual machine.

Firewall rules

If you have firewall enabled in Debian 12, and it's using the default nftables, disable it. K3s creates its own firewall rules (such as forwarding traffic between containers), and these may conflict with other rules. Suggestion for turning off firewall is also stated in Official K3s documentation.

Leave only these lines in nftables config file to disable your rules:

$ sudo vim /etc/nftables.conf
/etc/nftables.conf
#!/usr/sbin/nft -f

flush ruleset

Reload rules with command:

$ sudo systemctl restart nftables.service

To view the firewall ruleset, use following command:

$ sudo nft list ruleset

Tip

If you want your single node K3s instance protected with firewall, enable firewall for virtual machine in Proxmox. Then open following ports using firewall:

  • TCP 22 - SSH access to virtual machine
  • TCP 443 - HTTPS for web applications running in containers. To run many applications on one port Ingress Controller will be used and it acts as reverse proxy allowing many applications to be accessible on one port, but under different URLs.

Installation

Run the installation script:

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

sudo sh -c <command> - run many commands with one sudo, here we have 2 commands - curl and after | sh

That is all. Now you have running K3s instance, and all required services are started automatically.

Kubectl utility

kubectl utility is installed with K3s but to use it you need root privileges and use sudo. If you want to run kubectl as user, follow these steps:

  • Create new group k3s and add your user to that group:
$ sudo groupadd k3s && \
  sudo usermod -aG k3s <user-name>

  • Login again to be in this new group.

  • Add group read and own permission to file /etc/rancher/k3s/k3s.yaml. This is necessary because K3s will revert file permissions to the default 600 if changed through normal methods:

$ sudo vim /etc/rancher/k3s/config.yaml
/etc/rancher/k3s/config.yaml
write-kubeconfig-mode: "0640"
write-kubeconfig-group: "k3s"

  • Restart k3s service:
$ sudo systemctl restart k3s.service

Enable autocompletion for kubectl

To enable bash autocompletion for kubectl (when using Tab key), run following command to add entry to user's .bashrc file:

$ echo -e "\n# kubectl completion bash" >> ~/.bashrc && \
  echo 'source <(kubectl completion bash)' >>~/.bashrc

echo -e - enable interpretation of backslash escapes

Login again or run following command to enable bash autocompletion in current session:

$ source ~/.bashrc

Test installation

Test if installation was completed by running commands:

$ kubectl get node -o wide
$ kubectl get all -A -o wide

Upgrade K3s

To upgrade K3s to new version re-run installation script using the same flags as when it was installed, in this case it will be:

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