Skip to content
← Back to Work
Cloud Native · Automation

k8s-cluster-bootstrap

  • Provisioning
  • Bare-metal
  • Automation

Summary

I built an open-source tool that installs an on-premises Kubernetes cluster with one command, to cut the manual steps and missed settings repeated on every installation. It handles pre-setup, runtime installation, cluster initialization, networking, and worker joins in one flow, so clusters are built the same way as nodes are added.

Role
DeveloperMaintainer
Outcome
K8s 1.24–1.36169 versions28 releases
Run the bootstrap once per node. Preflight, runtime and version-pinned Kubernetes components are common. The master runs kubeadm init and optional Calico deployment; workers retrieve the master’s join token over SSH and rsync, then run kubeadm join. Without a role option, only common components are installed.
Bootstrap Flow from a Single Command

Repeated setup produced inconsistent configurations

Whenever I installed an on-premises cluster, I had to configure memory swap, kernel, and network settings on each node and install the container runtime and Kubernetes components one by one. After initializing the master node and deploying the CNI, I passed the join token to each worker node. As the number of nodes grew, repeating these steps manually often resulted in misconfigurations caused by missed settings or different settings across nodes.

To reduce missing settings and unintended differences between nodes, installation steps needed to run in a consistent order while still allowing environment-specific values to be set separately. I grouped the prerequisite setup and runtime installation shared by all nodes into a common sequence, then separated master initialization and worker joins by node role. Kubernetes version, runtime, and network ranges are specified through command-line options, so the script can be used across environments without editing its code. I built a bootstrap script that runs the required setup and installation with one command per node, open-sourced it, and expanded its supported environments through 28 releases.

What one command does

Specify the node role and installation options, then run the script with sudo to automate the process from prerequisite setup to master initialization or a worker join. The video below shows a real installation of a master node on Ubuntu 22.04 with containerd and Kubernetes 1.31.0.

k8s-cluster-bootstrap Demo

To reduce missing settings on individual nodes, I included operating-system configuration in the same flow as package installation. The script disables swap and UFW and installs the selected runtime and Kubernetes components. It also applies the kernel-module and sysctl settings needed to run containers and handle network traffic, saving them in configuration files so they persist after a reboot.

After configuring the master node, I still had to pass join tokens to each worker, so I automated the node connection process as well. On the master, kubeadm initializes the cluster, and the script creates the kubeconfig and join command. Calico is deployed with the specified Pod network range, with VXLAN as the default and IPIP available as an option for the network environment. On each worker, the script retrieves the master's join command over SSH and runs it, reducing the work of copying tokens and entering join commands whenever a node is added.

Checking prerequisites and handling failures

As I expanded the supported versions, installations sometimes failed because the script inferred the deb package revision from the Kubernetes version. The revision registered in the repository could differ even for the same Kubernetes version. I changed the script to query the actual package version with apt-cache madison and install kubelet, kubeadm, and kubectl at that same version. After installation, apt-mark hold prevents package updates from unintentionally changing the Kubernetes version.

For the Docker runtime option, the script builds cri-dockerd from source to connect Docker to Kubernetes. Hard-coding the required Go version would mean editing the script whenever cri-dockerd changed its requirements, so it now reads the version from go.mod and installs that Go toolchain before building.

To catch invalid inputs before installation begins, the script first checks the options required for the node role, the runtime, and the supported Kubernetes version. It reads a VERSIONLIST next to the script first and fetches the list from GitHub if the local file is absent. If it cannot load the list or find a package for the requested version, it reports the error and stops installation rather than proceeding without confirming those prerequisites.

Supported environments and releases

It supports Ubuntu 18.04 through 26.04 and 169 Kubernetes versions from 1.24.15 through 1.36.4. After releasing it under Apache-2.0, I addressed installation issues and environment-specific differences through 28 releases. For on-premises cluster setup, the script handles the prerequisite configuration, runtime installation, and worker joins that I used to repeat manually, with one command per node.