Are you looking for an easy guide for installing Kubernetes Cluster on Debian 11 (Bullseye)?
The step-by-step guide on this page will demonstrate you how to install Kubernetes cluster on Debian 11 with Kubeadm utility.
Kubernetes (k8s) cluster contains master and worker nodes which are used to run containerized applications. Master node works as control plan and worker nodes offers environment for actual workload.
Prerequisites
- Minimal Installed Debian 11
- 2 CPU / vCPU
- 2 GB RAM
- 20 GB free disk space
- Sudo User with Admin rights
- Stable Internet Connectivity
Lab Setup
For the demonstration, I am using three Debian 11 systems with following details,
- Master Node (k8s-master) – 192.168.1.236
- Worker Node 1 (k8s-worker1) – 192.168.1.237
- Worker Node 2 (k8s-worker2) – 192.168.1.238
Without any further delay, let’s jump into the installation steps.
1 ) Set Host Name and update /etc/hosts file
Use hostnamectl command to set the hostname on master and worker nodes.
$ sudo hostnamectl set-hostname "k8s-master" // Run on master node $ sudo hostnamectl set-hostname "k8s-worker1" // Run on 1st worker node $ sudo hostnamectl set-hostname "k8s-worker2" // Run on 2nd worker node
Add the following entries in /etc/hosts file on all the nodes,
192.168.1.236 k8s-master 192.168.1.237 k8s-worker1 192.168.1.238 k8s-worker2
2) Disable Swap on all nodes
For kubelet to work smoothly, it is recommended to disable swap. Run following commands on master and worker nodes to turn off swap.
$ sudo swapoff -a $ sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab
3) Configure Firewall Rules for Kubernetes Cluster
In case, OS firewall is enabled on your debian systems then allow following ports on master and worker nodes respectively.
On Master node, run
$ sudo ufw allow 6443/tcp $ sudo ufw allow 2379/tcp $ sudo ufw allow 2380/tcp $ sudo ufw allow 10250/tcp $ sudo ufw allow 10251/tcp $ sudo ufw allow 10252/tcp $ sudo ufw allow 10255/tcp $ sudo ufw reload
On Worker Nodes,
$ sudo ufw allow 10250/tcp $ sudo ufw allow 30000:32767/tcp $ sudo ufw reload
Note: If firewall is disabled on your Debian 11 systems, then you can skip this step.
4) Install Containerd run time on all nodes
Containerd is the industry standard container run time, we must install containerd on all master and worker nodes.
Before installing containerd, set the following kernel parameters on all the nodes.
$ cat <<EOF | sudo tee /etc/modules-load.d/containerd.conf overlay br_netfilter EOF $ sudo modprobe overlay $ sudo modprobe br_netfilter $ cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes-k8s.conf net.bridge.bridge-nf-call-iptables = 1 net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-ip6tables = 1 EOF
To make above changes into the effect, run
$ sudo sysctl --system
Now, install conatinerd by running following apt command on all the nodes.
$ sudo apt update $ sudo apt -y install containerd
Configure containerd so that it works with Kubernetes, run beneath command on all the nodes
$ containerd config default | sudo tee /etc/containerd/config.toml >/dev/null 2>&1
Set cgroupdriver to systemd on all the nodes,
Edit the file ‘/etc/containerd/config.toml’ and look for the section ‘[plugins.”io.containerd.grpc.v1.cri”.containerd.runtimes.runc.options]’ and add SystemdCgroup = true
$ sudo vi /etc/containerd/config.toml
Save and close the file.
Restart and enable containerd service on all the nodes,
$ sudo systemctl restart containerd $ sudo systemctl enable containerd
5) Enable Kubernetes Apt Repository
Enable Kubernetes apt repository on all the nodes, run
$ sudo apt install gnupg gnupg2 curl software-properties-common -y $ curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmour -o /etc/apt/trusted.gpg.d/cgoogle.gpg $ sudo apt-add-repository "deb http://apt.kubernetes.io/ kubernetes-xenial main"
6) Install Kubelet, Kubectl and Kubeadm on all nodes
Run the following apt commands on all the nodes to install Kubernetes cluster components like kubelet, kubectl and Kubeadm.
$ sudo apt update $ sudo apt install kubelet kubeadm kubectl -y $ sudo apt-mark hold kubelet kubeadm kubectl
7) Create Kubernetes Cluster with Kubeadm
Now, we are all set to create Kubernetes cluster, run following command only from master node,
$ sudo kubeadm init --control-plane-endpoint=k8s-master
Output,
Above output confirms that control plane has been initialized successfully. In the output, we have commands for regular user for interacting with the cluster and also the command to join any worker node to this cluster.
To start interacting with cluster, run following commands on master node,
$ mkdir -p $HOME/.kube $ sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config $ sudo chown $(id -u):$(id -g) $HOME/.kube/config
Run following kubectl command to get nodes and cluster information,
$ kubectl get nodes $ kubectl cluster-info
Output of above commands,
Join both the worker nodes to the cluster by running ‘Kubeadm join’ command.
Note: Copy the exact command from the output of ‘kubeadm init’ command. In my case, following is the command
$ sudo kubeadm join k8s-master:6443 --token ta622t.enl212euq7z87mgj \ --discovery-token-ca-cert-hash sha256:2be58f54458d0e788c96b8841f811069019161f9a3dd8502a38c773e5c6ead17
Output from Worker Node 1,
Output from Worker Nod 2 ,
Check the nodes status by running following command from master node,
$ kubectl get nodes NAME STATUS ROLES AGE VERSION k8s-master NotReady control-plane 23m v1.25.0 k8s-worker1 NotReady <none> 9m27s v1.25.0 k8s-worker2 NotReady <none> 2m19s v1.25.0 $
To make nodes status ready, we must install POD network addons like Calico or flannel.
8) Install Calico Pod Network Addon
On the master node, run beneath command to install calico,
$ kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.25.0/manifests/calico.yaml
Output,
Allow Calico ports in OS firewall, run beneath ufw commands on all the nodes,
$ sudo ufw allow 179/tcp $ sudo ufw allow 4789/udp $ sudo ufw allow 51820/udp $ sudo ufw allow 51821/udp $ sudo ufw reload
Verify the status of Calico pods, run
$ kubectl get pods -n kube-system
Perfect, now check nodes status again,
Great, output above confirms that master and worker nodes are in ready status. Now, this cluster is ready for the workload.
9) Test Kubernetes Cluster Installation
To test Kubernetes cluster installation, let’s try to deploy nginx based application via deployment. Run beneath commands,
$ kubectl create deployment nginx-app --image=nginx --replicas 2 $ kubectl expose deployment nginx-app --name=nginx-web-svc --type NodePort --port 80 --target-port 80 $ kubectl describe svc nginx-web-svc
Output of above commands,
Try to access the nginx based application using following curl command along with the nodeport 30036.
Note : In the curl command we can use either of worker node’s hostname.
$ curl http://k8s-worker1:30036
Above command’s output confirm that we are able to access our nginx based application.
That’s all from this guide, I hope you have found it informative and able to install Kubernetes cluster on Debian 11 smoothly. Kindly do post your queries and feedback in below comments section.
Thanks. This really helped me out!
Thank you very much for the detailed explanation! It helped me out to understand a lot.
One question: shouldn’t you add the NGINX port (30036 in your case) to the UFW allowed ports?
If I follow strictly your tutorial, the curl command is blocked until I explicitely allow the port on the remote host.
Hi Sovattha,
In case firewall is up and running on your Debian system before actual Kubernetes cluster installation then you must allow node port in the firewall.
Thanks, this is really useful!
Very good, thank you very much for sharing!
Thanks for this guide! Easy to follow and useful!
The current version of Kubernetes (v1.26) remove support for containerd <=1.5 (‘https://kubernetes.io/blog/2022/11/18/upcoming-changes-in-kubernetes-1-26/#cri-api-removal’).
In Debian 11's stable branch, containerd v1.4.3 is used:
containerd/stable 1.4.13~ds1-1~deb11u3 amd64
To resolve, you'll need to install containerd from Debian's unstable branch which uses v1.6.14.
Yes you do need it.
The easy way I found was to add the following repo to my source list:
sudo nano /etc/apt/sources.list
#Deb unstable
deb http://ftp.ca.debian.org/debian sid main
Save and exit
the run sudo apt update
To see the available versions run:
$ apt-cache madison containerd
To install specific version
sudo apt install containerd=1.6.16~ds1-1
thank you so match!!
great post
The file does not exist ?
‘https://docs.tigera.io/calico/manifests/calico.yaml’
Hi Matt,
Please use the following latest calico yaml file,
kubectl apply -f ‘https://raw.githubusercontent.com/projectcalico/calico/v3.25.0/manifests/calico.yaml’
Thank you very much for the tutorial!!
Right now, the URL
“https://projectcalico.docs.tigera.io/manifests/calico.yaml”
does not exist anymore (did work a week ago). It seems that installing calico is more complicated, now.
Flannel is an alternative, that does still work with ease. One should:
– add “–pod-network-cidr=10.244.0.0/16” to kubeadm init and then
– kubectl apply -f “https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml”
In terms of getting the CRI, docker is an alternative to messing with the debian unstable repository:
– add “deb https://download.docker.com/linux/debian bullseye stable” to sources.list and add key as described on docker website
– apt install containerd.io
This should provide more frequent updates. Debian repos might be to static relative to kubernetes. It does also allow for installing docker-ce in parallel if someone wants to build on the master node, for example.
P.S. Would you consider writing a tutorial on running a private registry? With kubernetes 1.26.1 and modern CRI, the certificate issues become much more challenging. I think that the instructions on “insecure registries” and “skip verification” no not work anymore.