Skip to content
← Back to Work
Cloud Native · Automation

k8s-cluster-bootstrap

An installation tool that configures on-premises Kubernetes runtimes, networking, and pinned versions with one command.

K8s 1.24–1.36 · 170 versions

  • Provisioning
  • Bare-metal
  • Automation
GitHub ↗
one command sudo bootstrap Preflight swap · modules · sysctl Runtime cri-dockerd Components kubelet · kubeadm · kubectl Master kubeadm init CNI Calico Workers kubeadm join
Bootstrap flow — a single command runs from preflight through runtime and component install to master init, CNI deploy, and worker join.

Repeated setup produced inconsistent configurations

Each on-premises cluster required the same swap, kernel, and network setup, followed by runtime and Kubernetes component installation. After master initialization and CNI deployment, every worker needed a join token. More nodes meant more opportunities for omissions or inconsistent settings.

Setting up on-premises clusters over and over made that inefficiency obvious, so I built a bootstrap that finishes it in a single command. It is open-sourced and I have maintained it across 28 releases.

What one command does

Run the script with sudo and a few options, and it handles everything from pre-setup to a finished cluster in one flow. The clip below is a real run bootstrapping a master node with a single command.

k8s-cluster-bootstrap demo
  • Pre-setup: disables swap, clears the firewall, loads the overlay and br_netfilter kernel modules, and persists iptables-bridging sysctl
  • Runtime & components: installs cri-dockerd (or containerd) and registers the systemd service, plus kubelet/kubeadm/kubectl
  • Master: kubeadm init (with the chosen K8s version, host IP, pod CIDR, CRI socket), creates .kube/config, and issues the join token
  • CNI: auto-deploys Calico. Waits for the API to stabilize, then applies the pod CIDR and encapsulation (cloud-safe VXLAN by default, IPIP for bare-metal)
  • Workers: fetch the join token from the master over sshpass/rsync and run kubeadm join automatically

Checking prerequisites and handling failures

The script checks network and package prerequisites and exposes environment differences as options. Thirteen flags cover master/worker mode (-m/-w), master IP (-i), Calico CIDR (-c), runtime (-ct), encapsulation (-e), Kubernetes version (-v), metrics-server (-ms), non-root kubeconfig (-r), and other settings.

  • Compiles cri-dockerd from source instead of depending on a binary, detecting the required Go version from go.mod and installing the toolchain automatically
  • Resolves the exact deb revision via apt-cache madison (patch revisions vary) and pins with apt-mark hold to block accidental upgrades, supporting 170 Kubernetes versions from 1.24.15 through 1.36.4
  • Handles failures: dual-source GPG failover, a check that the master IP is private and does not collide with the pod CIDR, and apt-lock cleanup
  • Reads the supported-version list from GitHub or a local VERSIONLIST for offline use, with colored info/success/warning/danger output for at-a-glance progress

Supported environments and releases

It runs on Ubuntu 18.04 through 26.04, is open-sourced under Apache-2.0, and has 28 releases from v0.1.1 to v1.3.0. Written as ~723 lines of defensive bash (error-status checks, return-code guards), it is used as-is for the real work of repeatedly standing up on-premises clusters.