Skip to content

How to Prepare a Bare-Metal Debian Node for Kubernetes

Before installing Kubernetes binaries on a bare-metal machine (like we do in the homelab project), the underlying operating system must be strictly configured. Kubernetes expects total control over system resources and networking.

Here are the crucial steps required to harden and configure a headless Debian server for Kubernetes.

1. Disable Swap Memory

Kubernetes’ scheduler works by calculating exact RAM usage per pod. If the OS can quietly dump memory to a hard drive swap file, the scheduler's calculations become invalid.

First, turn it off for the current session: 

sudo swapoff -a

Then, comment out the swap entry in /etc/fstab so it stays off after a reboot: 

sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

2. Load Kernel Modules

For your pods to talk to the internet and to each other across different nodes, the Linux kernel needs specific networking features enabled.

Load the overlay and br_netfilter modules: 

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

3. Configure sysctl

You must allow IPv4 forwarding and allow iptables to see bridged traffic. This is mandatory for your Container Network Interface (CNI) like Flannel or Cilium.

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

4. Install and Configure Containerd

Modern Kubernetes requires that the container runtime uses systemd to manage cgroups (resource limits) rather than trying to manage them itself.

After installing containerd, generate the default config and flip SystemdCgroup = true:

sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
sudo systemctl restart containerd

Note: In the homelab project, these exact steps are automated via Ansible playbooks (00-bootstrap-debian.yaml and 01-install-containerd.yaml) to guarantee idempotency across all nodes.