Kubernetes Control Plane on Docker

This project runs Kubernetes control plane components using Docker containers. It sets up a complete Kubernetes API server, controller manager, scheduler, and etcd database. In this repo you will find the bases of a MKS (Managed Kubernetes Service). Cloud providers may use a similar but more robust approach. With this setup, you could just install kubelet on a node and join it to your control plane.

What This Does

This setup creates a Kubernetes control plane that includes:

• etcd: Stores all cluster data
• kube-apiserver: Main API that handles requests
• kube-controller-manager: Manages cluster state
• kube-scheduler: Decides where to place pods

Before Running Docker Compose

Things You Need to Do First

1. Set Environment Variables Create a .env file in this folder with these settings:

   ETCD_VERSION=3.6.0
   KUBE_VERSION=1.33.0
   INTERNAL_NETWORK_SUBNET=172.18.0.0/16

   You can use the Kubernetes and etcd versions you prefer. Make sure they work together.

2. Generate Kubernetes Security Files (PKI and Config)

   Kubernetes needs secure communication between all parts. This uses TLS certificates and config files that tell each part how to connect safely.

   Step 1: Create a temporary container with kubeadm

   We use kubeadm (a Kubernetes tool) to create all the security files automatically. In this folder, run:

   docker run --name kubeadm --rm -it --privileged ubuntu:24.04 bash

   Step 2: Install kubeadm inside the container

   Run these commands inside the container:

   # Update system and install tools
   apt update && apt install -y curl apt-transport-https ca-certificates gnupg lsb-release
   
   # Add Kubernetes software source
   curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | gpg --dearmor -o /etc/apt/trusted.gpg.d/k8s.gpg
   echo "deb https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /" > /etc/apt/sources.list.d/kubernetes.list
   
   # Install kubeadm
   apt update && apt install -y kubeadm
   
   # Install text editor (optional)
   apt install -y vim

   Step 3: Create the cluster config file

   Inside the container, create a file called cluster-config.yaml:

   vim cluster-config.yaml

   Copy the content from the cluster-config.yaml file in this repository into the container.

   Step 4: Generate all security files

   Still inside the container, run:

   # Create all certificates
   kubeadm init phase certs all --config cluster-config.yaml
   
   # Create all config files
   kubeadm init phase kubeconfig all

   Step 5: Copy files to your computer

   Open a new terminal window (keep the container running), go to this repository folder, and run:

   docker cp kubeadm:/etc/kubernetes .

   Step 6: Clean up

   Go back to the container terminal and exit:

   exit

   You should now have a kubernetes folder with all the security files needed.

3. Check That Everything is Ready

   Make sure these folders and files exist:

   ./kubernetes/pki/                    (certificates folder)
   ./kubernetes/pki/etcd/               (etcd certificates)
   ./kubernetes/admin.conf              (admin access file)
   ./kubernetes/scheduler.conf          (scheduler config)
   ./kubernetes/controller-manager.conf (controller config)
   

How to Run

1. Start All Services

   docker compose up -d

2. Check if Everything is Running

   docker compose ps

3. View Logs if Something Goes Wrong

   # See all logs
   docker compose logs
   
   # See logs for one service
   docker compose logs kube-apiserver

How to Stop

docker compose down

To also remove stored data:

docker compose down -v

What Each Component Does

• etcd: A database that stores all cluster information
• kube-apiserver: The main server that handles all requests to Kubernetes
• kube-controller-manager: Watches the cluster and makes sure everything is working correctly
• kube-scheduler: Decides which node should run new pods

Troubleshooting

Problem: Services won't start

• Solution: Check if certificates exist in ./kubernetes/pki/

Problem: Can't connect to API server

• Solution: Make sure port 6443 is not blocked by firewall

Problem: etcd fails to start

• Solution: Check if etcd data directory has correct permissions

Problem: Components can't talk to each other

• Solution: Verify all config files exist and have correct server addresses

Network Setup

All components run on a custom Docker network (172.18.0.0/16) so they can talk to each other using their container names.