kubeadm

Create a Kubernetes control plane

$ kubeadm init

$ kubeadm join --token [token]

$ kubeadm token create --ttl [12h0m0s]

$ kubeadm upgrade plan

$ kubeadm upgrade apply [version]

$ kubeadm config view

$ kubeadm reset

kubeadm command [flags]

Common commands:
kubeadm init [flags]
kubeadm join [flags]
kubeadm reset [flags]
kubeadm upgrade [flags]
kubeadm config [flags]
kubeadm token [flags]
kubeadm version

--apiserver-advertise-address=
    Used with init. The IP address the API Server will advertise to other cluster members.

--control-plane-endpoint=
    Used with init. Specify a stable IP address or DNS name for the control plane. Useful for HA setups.

--pod-network-cidr=
    Used with init. Specify range of IP addresses for the pod network. Required for a CNI plugin.

--kubernetes-version=
    Used with init. Choose a specific Kubernetes version for the control plane components.

--upload-certs
    Used with init. Upload certificates to a Secret in the cluster, allowing kubeadm join --control-plane to retrieve them securely.

--token=
    Used with join. The token used to discover the cluster-info and establish trust.

--discovery-token-ca-cert-hash=
    Used with join. Validate the root CA certificate hash to secure discovery.

--control-plane
    Used with join. Designate the joining node as an additional control plane instance for high availability.

--node-name=
    Used with init or join. Specify the node name to use for the joining machine.

--config=
    Path to a kubeadm configuration file (YAML) for advanced customization.

--help
    Help for any command or subcommand.

--v=
    Log level verbosity for debugging.

kubeadm is a powerful command-line utility used to bootstrap a minimum viable Kubernetes cluster on existing hardware. It handles the essential steps for setting up a production-grade cluster, including initializing the control plane, joining worker nodes, and installing core add-ons like CoreDNS and kube-proxy. kubeadm aims to provide a good "fast path" for users to get a cluster up and running, focusing on best practices and security. It simplifies the complex process of manual Kubernetes component configuration, allowing users to quickly experiment, develop, or deploy applications without deep cluster internals knowledge. While it automates many tasks, it also provides flexibility through configuration files and flags for advanced scenarios, such as high availability setups or custom networking. It's often used in conjunction with a CNI (Container Network Interface) plugin for pod networking and a container runtime like containerd.

kubeadm does not provision underlying infrastructure (VMs, bare-metal). It also does not install a Container Network Interface (CNI) plugin for pod networking (which must be done manually after init), nor does it manage the container runtime (e.g., containerd, Docker). It is a building block for cluster setup, not a full provisioning solution. Upgrading clusters can be complex and requires careful planning, especially across major Kubernetes versions. For production environments, consider additional steps for high availability, persistent storage, and comprehensive security beyond kubeadm's scope.

The typical workflow involves preparing machines (OS, container runtime, necessary kernel modules, networking), running kubeadm init on the chosen control plane node, then installing a CNI plugin (e.g., Calico, Flannel), and finally running kubeadm join on worker nodes. For high availability, additional control plane nodes can also join using kubeadm join --control-plane.

Before initializing or joining a cluster, kubeadm automatically performs a series of pre-flight checks. These checks validate that the environment meets all necessary prerequisites, covering aspects such as network connectivity, required open ports, container runtime status, kernel modules, and system configurations. This helps prevent common setup issues and provides clear guidance if problems are detected.

While many settings can be controlled via command-line flags, kubeadm supports comprehensive YAML-based configuration files. These files allow users to specify detailed settings for various Kubernetes components (like the API Server, Controller Manager, and Scheduler), manage certificates, define network parameters, and configure other advanced options, providing a robust way to manage complex cluster setups.

kubeadm was first introduced in Kubernetes 1.4 (around September 2016) as a crucial tool to simplify the process of bootstrapping Kubernetes clusters. Its primary goal was to abstract away the intricate manual configurations of Kubernetes components, making cluster setup more accessible. Over its development, kubeadm has undergone significant improvements, gaining stability, better support for high availability (HA) control planes, streamlined cluster upgrades, and more robust pre-flight checks. It has evolved into the official and recommended tool for Kubernetes cluster bootstrapping within the community, with new features and enhancements released alongside each Kubernetes version.

kubectl(1), minikube(1), kind(1), crictl(8), systemctl(1)