Skip to main content

Debian Kubernetes

Introduction

Kubernetes (often abbreviated as K8s) is an open-source container orchestration platform that automates the deployment, scaling, and management of containerized applications. When combined with Debian's stability and security, it creates a powerful foundation for modern cloud-native infrastructure.

In this guide, we'll explore how to set up and manage Kubernetes on Debian systems. This combination is particularly popular in production environments due to Debian's reliability and Kubernetes' robust container orchestration capabilities.

Prerequisites

Before we begin, ensure you have:

  • A Debian system (Debian 11 "Bullseye" or newer recommended)
  • Root or sudo access
  • Basic understanding of Linux commands
  • Familiarity with container concepts (Docker/Podman)

Understanding Kubernetes Architecture

Kubernetes follows a master-worker architecture that consists of several key components:

  • Control Plane (Master): Manages the cluster

    • API Server: Serves the Kubernetes API
    • etcd: Stores cluster configuration
    • Scheduler: Assigns workloads to nodes
    • Controller Manager: Maintains desired state
  • Worker Nodes: Run containerized applications

    • Kubelet: Ensures containers are running
    • Kube Proxy: Networking rules for services
    • Container Runtime: Runs containers (Docker, containerd, etc.)

Setting Up Kubernetes on Debian

Let's walk through the process of setting up a Kubernetes cluster on Debian systems.

1. System Preparation

First, update your system and install prerequisites:

bash
# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

2. Install Container Runtime (containerd)

Kubernetes needs a container runtime. Let's install containerd:

bash
# Install containerd
sudo apt install -y containerd

# Create default configuration
sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml > /dev/null

# Configure containerd to use systemd cgroups
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml

# Restart containerd
sudo systemctl restart containerd
sudo systemctl enable containerd

3. Install Kubernetes Components

Now we'll install the three main Kubernetes components: kubeadm, kubelet, and kubectl.

bash
# Add Kubernetes apt repository
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# Update apt and install components
sudo apt update
sudo apt install -y kubelet kubeadm kubectl

# Prevent automatic updates
sudo apt-mark hold kubelet kubeadm kubectl

4. Configure System Settings

Prepare the system for Kubernetes:

bash
# Load required kernel modules
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# Configure sysctl for networking
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

# Apply sysctl parameters
sudo sysctl --system

# Disable swap (required for Kubernetes)
sudo swapoff -a

# Make it permanent by commenting out swap entries in /etc/fstab
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

5. Initialize Kubernetes Cluster (Master Node)

If this is your master node, initialize the cluster:

bash
# Initialize the cluster with a pod network CIDR
sudo kubeadm init --pod-network-cidr=10.244.0.0/16

# Example output:
# Your Kubernetes control-plane has initialized successfully!
#
# To start using your cluster, you need to run the following as a regular user:
# mkdir -p $HOME/.kube
# sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
# sudo chown $(id -u):$(id -g) $HOME/.kube/config
#
# You should now deploy a pod network to the cluster.
# Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
# https://kubernetes.io/docs/concepts/cluster-administration/addons/
#
# Then you can join any number of worker nodes by running the following on each as root:
#
# kubeadm join 192.168.1.100:6443 --token abcdef.0123456789abcdef \
# --discovery-token-ca-cert-hash sha256:1234...cdef

Follow the instructions from the output:

bash
# 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/config

6. Install a Network Plugin

Deploy a Container Network Interface (CNI) to enable pod-to-pod communication:

bash
# Install Flannel CNI
kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

7. Join Worker Nodes

On each worker node, run the kubeadm join command that was output during the initialization:

bash
# Example (your command will be different)
sudo kubeadm join 192.168.1.100:6443 --token abcdef.0123456789abcdef \
--discovery-token-ca-cert-hash sha256:1234...cdef

If you need to generate a new token:

bash
# Generate a new token on the master node
kubeadm token create --print-join-command

Verifying the Cluster

Check your cluster status:

bash
# Check node status
kubectl get nodes

# Example output:
# NAME STATUS ROLES AGE VERSION
# master-01 Ready control-plane 10m v1.29.2
# worker-01 Ready <none> 5m v1.29.2
# worker-02 Ready <none> 5m v1.29.2

Deploying Your First Application

Let's deploy a simple web application to test our cluster:

bash
# Create a deployment for the NGINX web server
kubectl create deployment nginx --image=nginx

# Expose the deployment as a service
kubectl expose deployment nginx --port=80 --type=NodePort

# Check the deployed service
kubectl get svc nginx

# Example output:
# NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
# nginx NodePort 10.96.100.123 <none> 80:31234/TCP 1m

You can now access the NGINX web server by visiting any node IP address with the assigned NodePort (e.g., http://192.168.1.101:31234).

Common Kubernetes Commands

Here are some essential commands for managing your Kubernetes cluster:

bash
# View all resources in the cluster
kubectl get all

# View pods in all namespaces
kubectl get pods --all-namespaces

# Describe a specific pod for detailed info
kubectl describe pod <pod-name>

# View logs for a pod
kubectl logs <pod-name>

# Execute a command in a pod
kubectl exec -it <pod-name> -- /bin/bash

# Delete a resource
kubectl delete deployment <deployment-name>

# Apply a configuration from a file
kubectl apply -f my-config.yaml

Kubernetes on Debian for Production

For production environments, consider these best practices:

  1. High Availability: Configure multiple master nodes for high availability
  2. Secure Communication: Enable TLS for all cluster communications
  3. Resource Management: Set resource limits for all deployments
  4. Monitoring: Implement monitoring with Prometheus and Grafana
  5. Backups: Regularly back up etcd data
  6. Updates: Plan for regular updates of both Debian and Kubernetes

Example Production Setup

Here's a YAML configuration for a simple but resilient web application deployment:

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: webapp
labels:
app: webapp
spec:
replicas: 3
selector:
matchLabels:
app: webapp
template:
metadata:
labels:
app: webapp
spec:
containers:
- name: webapp
image: nginx:latest
ports:
- containerPort: 80
resources:
limits:
memory: "128Mi"
cpu: "500m"
requests:
memory: "64Mi"
cpu: "250m"
livenessProbe:
httpGet:
path: /
port: 80
initialDelaySeconds: 30
periodSeconds: 10

Apply this configuration with:

bash
kubectl apply -f webapp-deployment.yaml

Troubleshooting Common Issues

Pods Stuck in Pending State

If pods are stuck in a pending state, check node resources:

bash
# Check node capacity
kubectl describe nodes

# Look for "Allocatable" and "Allocated resources" sections

Networking Issues

If pods can't communicate:

bash
# Check if DNS pods are running
kubectl get pods -n kube-system | grep coredns

# Check network plugin pods
kubectl get pods -n kube-system | grep flannel

Node Not Ready

If a node shows "NotReady" status:

bash
# Check kubelet status
sudo systemctl status kubelet

# View kubelet logs
sudo journalctl -u kubelet

Summary

In this guide, we've covered:

  1. The basics of Kubernetes architecture and components
  2. How to install and configure Kubernetes on Debian systems
  3. Deploying your first application to the cluster
  4. Essential commands for managing your Kubernetes resources
  5. Best practices for production deployments
  6. Troubleshooting common issues

Kubernetes on Debian provides a solid foundation for running containerized applications with the reliability and security that Debian is known for. As you become more familiar with this setup, you'll be able to deploy more complex applications and take advantage of advanced Kubernetes features like auto-scaling, rolling updates, and more.

Additional Resources

Exercises

  1. Deploy a stateful application like MySQL to your Kubernetes cluster.
  2. Configure persistent storage using Persistent Volumes.
  3. Set up an Ingress controller to manage external access to services.
  4. Implement auto-scaling for a deployment based on CPU usage.
  5. Create a multi-tier application with frontend, backend, and database services.


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)