Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 78 ยท Getting Started

Building a Cluster with kubeadm

Build a multi-node Kubernetes cluster step by step with kubeadm: prerequisites, containerd, kubeadm init and join, installing a CNI plugin, and quicker kind or k3s options.

Local tools such as kind and minikube hide how a cluster is put together. kubeadm is the opposite: it is the official, low-level tool that turns a few Linux machines into a Kubernetes cluster, and it shows every moving part. Production clusters, certification exams (CKA) and many on-premises setups use it, directly or under another installer, so it is worth building one once.

This lesson walks through the whole path: machine prerequisites, installing a container runtime and the Kubernetes packages, kubeadm init on a control plane node, installing a network plugin, and kubeadm join on workers. It ends with the faster alternatives (kind and k3s) for multi-node practice. A cluster cannot run on this site, so every command is read-only: run them on your own Linux machines or VMs. The two runnable examples are Python models of the preflight checks and of the "NotReady until CNI" behavior.

What you need

  • Two or more Linux machines (VMs are fine): one control plane, one or more workers. A supported distribution such as Ubuntu or Debian (apt) or Rocky/Fedora (dnf).
  • Resources: at least 2 CPUs and about 2 GB of RAM on the control plane node, and about 1-2 GB on workers (more for real workloads).
  • Network: full connectivity between the machines, a unique hostname, MAC address and product_uuid per machine (cloned VMs often break this).
  • Swap off. The kubelet refuses to start with swap enabled by default.
  • Open ports on the control plane: 6443 (API server), 2379-2380 (etcd), 10250 (kubelet), 10257 (controller manager), 10259 (scheduler). On workers: 10250 and the NodePort range 30000-32767.
  • Root access (sudo) on every machine.

The model below runs the kind of checks kubeadm does in its preflight phase, so you can see how failures read. Change the host dictionaries to see messages disappear.

Python Preflight checks before kubeadm init and join

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The real preflight is stricter and more detailed (it also checks for existing manifests, ports, the kernel and more), but these are the failures you will meet in practice.

Step 1: prepare every node

Run these on every machine (control plane and workers).

Terminal
# 1. turn swap off now and after reboots
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

# 2. kernel modules and network settings Kubernetes networking needs
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.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
sudo sysctl --system

overlay is the filesystem containers use; br_netfilter lets iptables see bridged traffic; ip_forward lets the node route packets between Pods (CNI and Pod Networking, kube-proxy Internals).

Step 2: install a container runtime

Kubernetes talks to a runtime through the Container Runtime Interface. The most common choice is containerd (the same runtime inside Docker), installed from your distribution or from Docker's apt repository (Runtimes and OCI).

Terminal
sudo apt-get update && sudo apt-get install -y containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml >/dev/null

Then edit /etc/containerd/config.toml and set SystemdCgroup = true under the runc.options section, so the runtime and the kubelet agree on one cgroup manager (the usual cause of random Pod restarts is a mismatch here):

Terminal
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl enable containerd

Step 3: install kubeadm, kubelet and kubectl

Install the three packages from the official Kubernetes package repository (pkgs.k8s.io), which has one repository per minor version. The key and repository lines are on the Kubernetes install page; they look like this (replace v1.36 with the minor version you want):

Terminal
sudo apt-get install -y apt-transport-https ca-certificates curl gpg
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.36/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.36/deb/ /' \
  | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
sudo systemctl enable --now kubelet
  • kubeadm bootstraps the cluster, kubelet runs on each node and starts Pods, kubectl is the CLI.
  • apt-mark hold stops a routine apt upgrade from changing the version; upgrading is a deliberate procedure (Cluster Upgrades and Maintenance).
  • After this the kubelet restarts every few seconds in a crash loop. That is normal: it is waiting for kubeadm init or join to give it a configuration.

Step 4: initialize the control plane

On the control plane node:

Terminal
sudo kubeadm init \
  --pod-network-cidr=10.244.0.0/16 \
  --control-plane-endpoint=cp.example.internal:6443
  • --pod-network-cidr is the address range for Pods. It must not overlap your node network, and some CNI plugins expect a specific range (Flannel expects 10.244.0.0/16; Calico and Cilium are flexible).
  • --control-plane-endpoint is a stable DNS name or load balancer address for the API server. Set it from the beginning if you may later add more control plane nodes (high availability), because changing it afterwards is painful. For a single lab node you can leave it out.

The command runs phases you can list with kubeadm init --help: preflight checks, generating a certificate authority and certificates, writing kubeconfig files, writing the static Pod manifests for the API server, controller manager, scheduler and etcd (Static Pods), waiting for the control plane to become healthy, uploading configuration, and installing CoreDNS and kube-proxy as add-ons. It finishes by printing two things you must save: how to set up kubectl, and the kubeadm join command for workers.

Set up kubectl for your user:

Terminal
mkdir -p $HOME/.kube
sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
kubectl get nodes
TEXT
NAME   STATUS     ROLES           AGE   VERSION
cp-1   NotReady   control-plane   1m    v1.36.1

NotReady is expected here. The cluster has no Pod network yet.

You can also drive kubeadm init with a configuration file, which is repeatable and reviewable:

YAML
# kubeadm-config.yaml  (apiVersion differs by release; check kubeadm config print init-defaults)
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: v1.36.1
controlPlaneEndpoint: cp.example.internal:6443
networking:
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12
Terminal
sudo kubeadm init --config kubeadm-config.yaml

Step 5: install a network plugin (CNI)

Pods need a network, and Kubernetes does not ship one. You install a CNI plugin: Cilium, Calico, Flannel and Weave-style options exist (CNI and Pod Networking). Each is applied with a manifest or Helm chart from its documentation; for example:

Terminal
kubectl apply -f <manifest-url-from-your-chosen-CNI-docs>
kubectl get pods -n kube-system -w

Until a CNI is running, the node stays NotReady and the CoreDNS Pods stay Pending. That is the most common "my new cluster is broken" moment, and it is not broken. This model shows the sequence:

Python Nodes become Ready only after a CNI is installed

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 6: join the workers

On each worker (after steps 1-3), run the command that kubeadm init printed:

Terminal
sudo kubeadm join cp.example.internal:6443 \
  --token abcdef.0123456789abcdef \
  --discovery-token-ca-cert-hash sha256:<hash>
  • The token is a short-lived bootstrap credential (valid for 24 hours by default).
  • The CA cert hash lets the new node check that it is talking to the real control plane before it trusts it.

If the token expired or you lost the command, create a new one on the control plane:

Terminal
kubeadm token create --print-join-command

Then verify from the control plane:

Terminal
kubectl get nodes -o wide
kubectl get pods -A
TEXT
NAME       STATUS   ROLES           AGE   VERSION
cp-1       Ready    control-plane   9m    v1.36.1
worker-a   Ready    <none>          2m    v1.36.1
worker-b   Ready    <none>          2m    v1.36.1

The <none> role is cosmetic; label workers with kubectl label node worker-a node-role.kubernetes.io/worker= if you want a name there. A smoke test proves the cluster works end to end:

Terminal
kubectl create deployment hello --image=nginx:1.27 --replicas=2
kubectl expose deployment hello --port=80 --type=NodePort
kubectl get pods -o wide

Single-node clusters

The control plane node has a taint (node-role.kubernetes.io/control-plane:NoSchedule) so that normal workloads do not land on it. On a one-machine lab, remove the taint so Pods can run there (Taints and Tolerations):

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

What you still have to do

kubeadm gives you a working cluster, not a finished one. Plan for:

  • High availability: three control plane nodes behind a load balancer (kubeadm join --control-plane), with stacked or external etcd.
  • Backups of etcd and certificate renewal (Cluster Upgrades and Maintenance).
  • Storage (a CSI driver and StorageClass), ingress, metrics-server, logging and monitoring (Storage Classes, Ingress, Metrics and Monitoring).
  • Security hardening (Supply Chain and Cluster Hardening).
  • Teardown for experiments: sudo kubeadm reset on each node, then delete the leftover CNI config in /etc/cni/net.d and run iptables cleanup if needed.

Faster alternatives for multi-node practice

If you only want a multi-node cluster for learning, use a tool that does steps 1-6 for you:

kind runs each "node" as a Docker container. A multi-node cluster is a small config file:

YAML
# kind-multi.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
  - role: worker
  - role: worker
Terminal
kind create cluster --name lab --config kind-multi.yaml
kubectl get nodes

k3s is a lightweight, certified Kubernetes distribution that installs with one command and joins workers with a token:

Terminal
curl -sfL https://get.k3s.io | sh -                         # server
curl -sfL https://get.k3s.io | K3S_URL=https://SERVER:6443 K3S_TOKEN=<token> sh -   # agent

Both include a CNI, so nodes are Ready without step 5. See Running a Local Cluster for how they compare, and use kubeadm when you want to understand or operate the real thing.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Right after kubeadm init, kubectl get nodes shows the control plane as NotReady. Why?

    Nodes stay NotReady and CoreDNS stays Pending until a CNI plugin is installed. It is an expected step, not a failure.
  2. 2. Why must swap be disabled on kubeadm nodes?

    The kubelet fails its preflight check when swap is on, because memory limits and scheduling assume real memory.
  3. 3. What do the token and discovery-token-ca-cert-hash do in kubeadm join?

    The bootstrap token proves the node may join (valid 24 hours by default). The CA hash protects it from joining an impostor.
  4. 4. Which command prints a fresh join command after the token has expired?

    Run it on the control plane to create a new bootstrap token and print the full join command.
  5. 5. Why is --control-plane-endpoint worth setting at kubeadm init time?

    A stable DNS name or load balancer address lets clients and nodes survive adding or replacing control plane nodes. Changing it later is hard.

Summary

  • kubeadm builds a cluster from Linux machines: prepare nodes (swap off, kernel modules, sysctl), install containerd and the Kubernetes packages, kubeadm init, install a CNI, kubeadm join.
  • containerd should use the systemd cgroup driver (SystemdCgroup = true).
  • The control plane runs as static Pods, and init prints the kubectl setup and the join command; tokens expire after 24 hours.
  • NotReady nodes and Pending CoreDNS Pods right after init mean the CNI is missing, not that the install failed.
  • kubeadm leaves HA, backups, storage, ingress and monitoring to you. Use kind or k3s when you only want a quick multi-node cluster.

Next, learn how to look inside a node with Nodes: Status, Conditions, Leases, Cordon and Drain.