Bootstrap a Kubernetes Control Plane with kubeadm init

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster. Everything below changes a node's host state, so run it only on a throwaway VM that already has a container runtime and the kubeadm, kubelet and kubectl packages.

How kubeadm init turns a config file into a control plane

kubeadm init is a pipeline of phases: it creates certificates, writes kubeconfig files and static Pod manifests, starts the kubelet, then registers add-ons. A configuration file makes the run repeatable and exposes settings that have no flag. The usual exam trap is forgetting that the cluster is not usable until kubectl has credentials and a Pod network exists.

config file ──→ preflight ──→ certs (/etc/kubernetes/pki) ──→ kubeconfig (/etc/kubernetes/*.conf)
            ──→ etcd + control-plane manifests (/etc/kubernetes/manifests) ──→ kubelet-start
            ──→ wait-control-plane ──→ upload-config ──→ mark-control-plane ──→ bootstrap-token ──→ addon

1. Read the file before you run it

For v1.35 the kubeadm config API is kubeadm.k8s.io/v1beta4. A file can hold several documents separated by ---: InitConfiguration carries settings for this node only (node name, CRI socket, advertise address), while ClusterConfiguration carries cluster-wide ones (networking, etcd, component arguments). A small example of our own, saved as /root/practice-init.yaml:

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 10.20.0.11
  bindPort: 6443
nodeRegistration:
  name: lab-cp-01
  criSocket: unix:///var/run/containerd/containerd.sock
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
clusterName: sandbox-east
networking:
  podSubnet: 172.20.0.0/16
  serviceSubnet: 10.96.0.0/12

Note that v1beta4 changed component arguments such as kubeletExtraArgs and apiServer.extraArgs from a map into a list of name/value pairs. A file written in the old map style fails validation. These commands change nothing:

kubeadm config validate --config /root/practice-init.yaml
kubeadm config images list --config /root/practice-init.yaml
kubeadm config print init-defaults     # every field with its default

If the file uses an older API version, kubeadm config migrate prints the v1beta4 equivalent.

2. Rehearse, then initialize

kubeadm init --config /root/practice-init.yaml --dry-run
kubeadm init --config /root/practice-init.yaml

The dry run shows what each phase would do without applying it; the real run stops if a preflight check errors. Keep the config as the single source of settings: the kubeadm docs warn that mixing --config with other flags may not be allowed in some cases. Each phase can also be run alone with kubeadm init phase <name>, which is how you rerun one stage after a fix.

3. Give kubectl credentials

Init writes /etc/kubernetes/admin.conf, whose certificate belongs to the kubeadm:cluster-admins group (bound to cluster-admin). It also writes super-admin.conf in system:masters, a break-glass identity that bypasses RBAC; keep that one for emergencies. For root, either export KUBECONFIG=/etc/kubernetes/admin.conf or copy it to $HOME/.kube/config, as the init output suggests.

4. Install the Pod network, then wait for Ready

kubectl get nodes -o wide
kubectl -n kube-system get pods -o wide
kubectl describe node lab-cp-01 | grep -A8 Conditions

Right after init, CoreDNS sits in Pending; the kubeadm troubleshooting guide calls this expected until a Pod network add-on is installed. The node usually reports NotReady too, and the message on its Ready condition tells you whether the runtime's network is the reason. Apply the CNI manifests with kubectl apply -f, check that the plugin's Pod range agrees with podSubnet, then watch until the node turns Ready and CoreDNS runs.

Common mistakes

• Running kubectl before pointing it at admin.conf: it has no usable cluster entry and reports that the connection to the server was refused.
• A map-style extraArgs block copied from an old blog post into a v1beta4 file: kubeadm config validate rejects it before init ever runs.
• A Pod range in the CNI manifest that disagrees with podSubnet, or that overlaps a host network: the kubeadm docs warn this leads to networking problems that are slow to diagnose later.
• Reading the hostname instead of the registered node name: check nodeRegistration.name or kubectl get nodes.

Cleanup: on the practice VM, kubeadm reset reverts most of what init did (it does not clean CNI config or iptables rules for you). References: kubeadm init, kubeadm Configuration (v1beta4), Creating a cluster with kubeadm. Next, try joining a worker or installing a CNI.