Skip to content

Kubeadm cluster initialization process

Kubeadm is the standard tool used to bootstrap a Kubernetes cluster. The initialization process, typically triggered by kubeadm init, automates the setup of the control plane and configures the node for operation.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md]

Workflow Stages

The initialization follows a structured workflow to verify the system environment and start the necessary control plane components^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md]:

  1. [preflight] Running pre-flight checks: The system verifies that the host meets all requirements, such as the Docker version compatibility^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md].
  2. [certs] Generating certificates: The process generates the necessary SSL certificates and keys for secure communication between components, including the CA, API server, and etcd certificates^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md].
  3. [kubeconfig] Writing kubeconfig files: Configuration files are written to /etc/kubernetes, allowing components like the admin, controller-manager, and scheduler to authenticate with the API server^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md].
  4. [control-plane] Creating static Pod manifests: Manifests for core control plane components (kube-apiserver, kube-controller-manager, kube-scheduler) and etcd are created in /etc/kubernetes/manifests^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md].
  5. [wait-control-plane]: The system waits for the kubelet to boot up the control plane static Pods^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md].
  6. [bootstrap-token] Configuring RBAC: Bootstrap tokens are configured, and RBAC rules are applied to allow new nodes to join the cluster and request certificates^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md].
  7. [addons] Applying addons: Essential cluster addons, such as CoreDNS and kube-proxy, are applied at the end of the process^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md].

Prerequisites

Cgroup Driver Configuration

A common source of initialization failure is a mismatch between the cgroup driver of the kubelet and the container runtime (e.g., Docker).^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md] If kubelet uses systemd but Docker uses cgroupfs, the Health Check (often curl -sSL http://localhost:10248/healthz) will fail.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md] To fix this, the Docker daemon must be configured to use systemd by setting "exec-opts": ["native.cgroupdriver=systemd"] in /etc/docker/daemon.json.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md]

System Configuration

Before running kubeadm init, the underlying OS requires specific modifications: * Swap: Must be disabled (swapoff -a) and removed from /etc/fstab.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md] * SELinux: Should be set to permissive or disabled.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md] * Network Bridging: iptables must be configured to check bridged traffic via net.bridge.bridge-nf-call-ip6tables and net.bridge.bridge-nf-call-iptables.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md]

Post-Initialization Steps

Once the control plane initializes successfully, the user must configure access and networking^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md]:

  1. Configure kubectl: To manage the cluster, the admin configuration must be copied to the user's home directory: bash mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md]

  2. Deploy Pod Network: The cluster will not function until a Container Network Interface (CNI) plugin is deployed.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md] For tools like Flannel, the CIDR in the network YAML (e.g., 192.168.0.0/16) must match the --pod-network-cidr defined during initialization.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md] Nodes will typically show a NotReady status until this step is completed.^[400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md]

Sources

  • 400-devops-06-kubernetes-k8s-learning-00install-01-kubernetes.md