Kubernetes has become the de facto standard for container orchestration, enabling developers and DevOps teams to deploy, scale, and manage containerized applications efficiently. Whether you’re setting up a lab environment, learning Kubernetes, or preparing a single-node cluster for development, this guide walks you through installing and configuring a fully functional Kubernetes cluster on Debian12.
We’ll go step by step—from system preparation to deploying your first pod—so you can follow along easily and understand what each command does.
Prerequisites: A fresh Debian12 server or VM with sudo access and at least 4GB RAM (8GB+ recommended).
Step-by-Step Commands to Install Kubernetes
Step 1: Update system
Always start with an updated system to ensure all packages are current.
sudo apt update && sudo apt upgrade -yExplanation:
This updates the package index and upgrades all installed packages to their latest versions, ensuring your system is secure and stable before installing Kubernetes.
Step 2: Disable swap (required by Kubernetes)
Kubernetes does not support swap enabled on nodes. You must disable it.
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab
Explanation:
swapoff -a turns off all swap partitions.
The sed command comments out any line containing “swap” in /etc/fstab, preventing swap from being re-enabled after reboot.
Step 3: Load kernel modules & sysctl settings
Kubernetes requires certain kernel modules and network settings to function properly.
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF sudo modprobe overlay sudo modprobe br_netfilter
Explanation: These modules enable overlay networking (used by container runtimes) and bridge filtering (required for CNI plugins).
Now configure networking settings:
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 --systemExplanation:
- These settings allow the Linux bridge to pass traffic to iptables for filtering.
- They also enable IPv4 packet forwarding, which is essential for pod-to-pod communication across nodes.
Step 4: Install container runtime (containerd)
Kubernetes needs a container runtime. We’ll use containerd, a lightweight and secure option.
sudo apt install -y containerd
Now configure containerd for Kubernetes:
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 sudo systemctl enable containerd
Key Point: Setting SystemdCgroup = true ensures that containerd uses the systemd cgroup driver, which matches the kubelet configuration and avoids runtime errors.
Step 5: Install Kubernetes packages
Install the core Kubernetes tools:
sudo apt-get install -y apt-transport-https ca-certificates curl gpg
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
Add the official Kubernetes GPG key:
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpgAdd the repository to APT sources:
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.listUpdate and install the components:
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectlExplanation:
kubelet: Runs on every node and manages container lifecycle.kubeadm: Tool to bootstrap the cluster.kubectl: CLI for interacting with the cluster.apt-mark holdprevents accidental upgrades that could break your cluster.
Step 6: Initialize cluster
Now, initialize the control plane node:
sudo kubeadm init --pod-network-cidr=192.168.0.0/16
Why --pod-network-cidr?
This flag defines the IP range for pods. We use 192.168.0.0/16 here because Calico, our chosen CNI plugin, defaults to this range.
After initialization completes, follow the instructions to set up kubectl for your user:
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/configYou now have full access to the cluster via kubectl.
Step 7: Install Calico CNI
A CNI plugin is required for pod networking. We’ll use Project Calico, known for its performance and security.
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.3/manifests/calico.yaml
Note: This manifest supports the 192.168.0.0/16 CIDR. If you used a different range, modify the manifest accordingly.
Wait a moment for the pods to start:
kubectl get pods -n kube-systemYou should see Calico pods running.
Step 8: Make node schedulable (since single node)
By default, the control plane node is tainted so no workloads run on it. For single-node clusters (like labs or dev environments), we remove this taint:
kubectl taint nodes --all node-role.kubernetes.io/control-plane-
Explanation: This removes the taint that prevents scheduling on the master node, making it usable for workloads.
Step 9: Test cluster
Verify everything is working:
kubectl get nodes kubectl get pods -A
You should see your node in Ready state.
Deploy a simple Nginx web server:
kubectl create deployment nginx --image=nginx kubectl get podsCheck the pod and you’ll see:
NAME READY STATUS RESTARTS AGE
nginx-7cdbd8cdc9-5x4x2 1/1 Running 0 30s