Installing Kubernetes on Debian 12 with kubeadm and Configuring Control Plane and Worker Nodes

#Node setup#

• va, Master node

• ca, Worker node

• kr, Worker node

#Preparation#

Update the system to the latest version, then remove no-longer-needed packages and clean up cached packages.

1
sudo apt update && sudo apt full-upgrade -y
2
sudo apt autoremove
3
sudo apt autoclean

If the kernel was updated, reboot.

Kubernetes nodes must not have swap enabled, so you need to disable the swap partition.

Then edit the /etc/fstab file and comment out or remove the swap line (if any).

Enable forwarding and related settings:

1
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
2
overlay
3
br_netfilter
4
EOF
5

6
sudo modprobe overlay
7
sudo modprobe br_netfilter
8

9
# sysctl params required by setup, params persist across reboots
10
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
11
net.bridge.bridge-nf-call-iptables  = 1
12
net.bridge.bridge-nf-call-ip6tables = 1
13
net.ipv4.ip_forward                 = 1
14
EOF
15

16
# Apply sysctl params without reboot
17
sudo sysctl --system

According to the official Kubernetes documentation, you should install the official Docker packages, so follow the Docker official docs.

#Install Docker#

Remove any non-official Docker packages. If you followed this site’s earlier Docker introduction, you likely need to remove the non-official Docker. As for the difference between the official Docker packages and the Debian repository packages: the Debian repo usually ships an older Docker version; whether that matters depends on your needs.

Uninstall the non-official Docker packages to avoid conflicts with the official ones.

1
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done

Install from the official documentation:

1
sudo apt-get update
2
sudo apt-get install ca-certificates curl gnupg
3
sudo install -m 0755 -d /etc/apt/keyrings
4
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
5
sudo chmod a+r /etc/apt/keyrings/docker.gpg
6

7
echo \
8
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
9
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
10
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
11

12
sudo apt-get update
13
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Start Docker and enable it on boot:

1
sudo systemctl enable docker --now

Note: The official Docker packages are different from the docker-compose package in the Debian repository. With official Docker you use docker compose (Compose as a plugin). With the Debian package you use docker-compose as a standalone binary.

#Install cri-dockerd#

cri-dockerd is the shim that lets Kubernetes talk to Docker. cri stands for Container Runtime Interface.

1
git clone https://github.com/Mirantis/cri-dockerd.git
2
cd cri-dockerd
3
make cri-dockerd
4
sudo mkdir -p /usr/local/bin
5
sudo install -o root -g root -m 0755 cri-dockerd /usr/local/bin/cri-dockerd
6
sudo install packaging/systemd/* /etc/systemd/system
7
sudo sed -i -e 's,/usr/bin/cri-dockerd,/usr/local/bin/cri-dockerd,' /etc/systemd/system/cri-docker.service
8
sudo systemctl daemon-reload
9
sudo systemctl enable cri-docker.service
10
sudo systemctl enable --now cri-docker.socket

Note: building cri-dockerd from source requires Go. If you see an error about go not being found, install Go: sudo apt install golang

If later commands fail with socket connection issues, try rebooting the server and temporarily disabling the firewall.

#Install kubeadm, kubelet and kubectl#

This part is also based on the official documentation. Note that even though we are on Debian 11/12, we still use the xenial (Ubuntu 16.04 LTS) repository.

1
sudo apt-get update
2
sudo apt-get install -y apt-transport-https
3
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-archive-keyring.gpg
4
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
5
sudo apt-get update
6
sudo apt-get install -y kubelet kubeadm kubectl
7
sudo apt-mark hold kubelet kubeadm kubectl # prevent these three from being upgraded automatically

At this point, kubeadm is installed.

#Configure the cluster#

Official documentation

A very important topic is networking. There are many machines in a k8s cluster, but externally there may be only a single network interface. For example, if you host a website on k8s, there is only one IP address for external access, but every node in the cluster still needs an IP address for internal communication. These can be private or public addresses. Kubernetes itself does not provide a built-in networking solution; you need to install a plugin. See also the official documentation: installing addons.

Here we use https://www.tigera.io/project-calico/. Different CNI plugins have slightly different installation procedures.

1
sudo kubeadm init --pod-network-cidr 192.168.0.0/16 --cri-socket unix:///var/run/cri-dockerd.sock --control-plane-endpoint master-node-01.acytoo.net

1
mkdir -p $HOME/.kube
2
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
3
sudo chown $(id -u):$(id -g) $HOME/.kube/config

1
curl https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml -O
2
kubectl apply -f calico.yaml

1
kubectl get node
2
kubectl get pod
3
kubectl get pods --all-namespaces

1
sudo kubeadm join master-node-01.acytoo.net:6443 --token sluqvx.itdsjivbewuiinfx \
2
        --discovery-token-ca-cert-hash sha256:95669c834aa9e861aed6a08783d1f893223ec327ad2612aba016c2b457afb2345 \
3
        --cri-socket unix:///var/run/cri-dockerd.sock

#Possible errors#

While setting everything up, I ran into quite a few issues. In most cases, the command-line error messages were enough to understand what went wrong—for example, the cri-socket service failing to start (check whether it was installed correctly, try starting it manually, then reboot), or port conflicts when specifying the cri-socket, and so on.

The only problem that really took me some time was a worker node failing to connect to socket 8080 (running kubectl get nods would show connection refused on 8080), and the node being stuck in NotReady after kubeadm join. There are many discussions online, and many people say that worker nodes must also have $HOME/.kube/config/admin.conf. But even when I ran init first and then join, it still didn’t work. In the end, I deleted the problematic worker node from the control plane and ran the same join command again—and it worked, without any admin.conf file on the worker.

Delete a worker node from the control plane:

1
kubectl drain [node name] --ignore-daemonsets
2
kubectl delete node [node name]

#Check status#

Back on the control plane node, list the nodes:

1
kubectl get nodes

#Conclusion#

Kubernetes has many configuration options, installation tools, and installation approaches. This article uses kubeadm as the installation method and Calico as the network plugin. In theory, the same approach works for Debian 10/11/12 and other Debian-based distributions such as Ubuntu.