How to Integrate Docker with Kubernetes on Debian 12 Bookworm System

Integrating Docker with Kubernetes is a powerful way to manage containerized applications at scale. Docker handles containerization, while Kubernetes orchestrates and automates deployment, scaling, and management of those containers. Debian 12 “Bookworm,” being a stable and widely used Linux distribution, offers a solid foundation for building a containerized development and production environment.

In this post, we’ll walk through the complete process of integrating Docker with Kubernetes on Debian 12. By the end, you’ll have a functional single-node Kubernetes cluster with Docker as its container runtime.

📋 Prerequisites

Before diving into the integration, ensure the following:

• You have a fresh installation of Debian 12 Bookworm.
• You have root or sudo privileges.
• Your system has at least 2 CPUs and 2 GB RAM.
• Internet connectivity is enabled.

🛠 Step 1: Update System Packages

Start by updating the system packages to their latest versions.

sudo apt update && sudo apt upgrade -y

Then, install basic tools required for the setup:

sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release software-properties-common

🐳 Step 2: Install Docker Engine on Debian 12

Docker is not available by default in Debian repositories with the latest versions. So, we need to add Docker’s official GPG key and repository.

2.1 Add Docker’s GPG key

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

2.2 Set up the Docker repository

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
  https://download.docker.com/linux/debian bookworm stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

2.3 Install Docker Engine

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

2.4 Start and Enable Docker

sudo systemctl enable docker
sudo systemctl start docker

You can verify the installation by running:

docker --version

🧱 Step 3: Configure Docker to Use Systemd Cgroup Driver

Kubernetes now prefers systemd as the cgroup driver for better compatibility.

3.1 Create or modify Docker daemon config

sudo mkdir -p /etc/docker

cat <<EOF | sudo tee /etc/docker/daemon.json
{
  "exec-opts": ["native.cgroupdriver=systemd"],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m"
  },
  "storage-driver": "overlay2"
}
EOF

3.2 Restart Docker

sudo systemctl daemon-reexec
sudo systemctl restart docker

☸️ Step 4: Install Kubernetes Components

We’ll install kubeadm, kubelet, and kubectl, the three core components for Kubernetes setup.

4.1 Add Kubernetes GPG key and repository

sudo curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-key.gpg

echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] \
  https://apt.kubernetes.io/ kubernetes-xenial main" | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list

4.2 Install Kubernetes packages

sudo apt update
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

🔧 Step 5: Disable Swap

Kubernetes requires swap to be disabled.

sudo swapoff -a

To permanently disable it:

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

🌐 Step 6: Set Up Kernel Modules and Sysctl Params

Kubernetes networking requires some kernel modules and settings.

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

sudo modprobe overlay
sudo modprobe br_netfilter

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

sudo sysctl --system

🧪 Step 7: Initialize Kubernetes Cluster

Now that everything is set up, initialize your cluster using kubeadm.

sudo kubeadm init --pod-network-cidr=192.168.0.0/16

Take note of the kubeadm join command output — it will be used to add other nodes.

👤 Step 8: Configure kubectl for the Regular User

To use kubectl as a non-root user:

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

🌐 Step 9: Install a Pod Network Add-On

To allow pods to communicate, install a network add-on. A popular choice is Calico.

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

Wait a few moments, then check node status:

kubectl get nodes

Your node should now show Ready status.

🧪 Step 10: Test the Setup

To confirm that everything is working, try running a simple pod:

kubectl run hello-world --image=nginx --port=80

Check that the pod is running:

kubectl get pods

Expose it via a service:

kubectl expose pod hello-world --type=NodePort --port=80

And find the NodePort assigned:

kubectl get svc hello-world

Access the Nginx page by visiting http://<your-server-ip>:<node-port>.

🔒 Optional: Remove Master Node Taint (For Single Node Dev Setup)

In a single-node setup, you might want to run workloads on the master node:

kubectl taint nodes --all node-role.kubernetes.io/control-plane-

🧼 Step 11: Useful Commands and Maintenance

Here are a few helpful commands for maintaining your setup:

• Restart kubelet:

  sudo systemctl restart kubelet
  

• View Kubernetes system status:

  kubectl get all --all-namespaces
  

• Drain and remove a node:

  kubectl drain <node-name> --delete-local-data --force --ignore-daemonsets
  kubectl delete node <node-name>
  

• Reset cluster:

  sudo kubeadm reset
  sudo rm -rf ~/.kube
  

🧠 Conclusion

Setting up Docker and Kubernetes on Debian 12 Bookworm is a straightforward process when you follow each step carefully. With Docker serving as the container runtime and Kubernetes orchestrating containers, you get a robust environment for building modern, scalable applications.

Whether you are preparing for a production setup or just experimenting in a development lab, this integration offers a reliable and flexible platform. Once your base setup is complete, you can explore advanced features like Helm charts, persistent storage, ingress controllers, and monitoring tools like Prometheus and Grafana.