kubeadm-ha: an Ansible wrapper for high availability Kubernetes clusters

Ansible playbooks behind a kubeadm install

kubeadm-ha is a project for building high availability Kubernetes clusters with kubeadm, using ansible-playbook to automate the installation. It offers both a one command install script and the option of executing the individual components step by step according to the playbooks.

That dual entry point is the design decision that matters. A single script is what you want the first time, when the cluster is a known-good set of machines and you want the result rather than the process. The numbered playbooks are what you want when something goes wrong halfway, or when the cluster already exists and you only want to add a node, or when you are rebuilding a certificate without touching the rest of the cluster.

The playbook list at the repository root is the clearest evidence of how the project is structured. The sequence starts with 00-kernel.yml and 01-base.yml, then 02-container-engine.yml and 03-kubernetes-component.yml, with 04-chrony.yml for time synchronisation, 05-load-balancer.yml, 06-etcd.yml, 07-kubernetes-certificates.yml, 08-kubernetes-master.yml and 09-kubernetes-worker.yml, and 10-post.yml at the end. After that come 21-network-plugin.yml, 22-ingress-controller.yml and 23-metrics-server.yml, and 31-docker-to-containerd.yml for migrating a container runtime.

The second group is the lifecycle set. 81 through 87 add or remove workers, masters, etcd members and nodes, and 90 onwards covers 90-init-cluster.yml, 91-upgrade-cluster.yml, 92-certificates-renew.yml, 93-backup-cluster.yml, 94-restore-cluster.yml and 99-reset-cluster.yml.

The primary language of the repository is recorded as Jinja, which is the templating engine Ansible uses, and the top level holds the ansible/ directory, a roles/ directory, an ansible.cfg, an offline/ directory for air-gapped installs and a Vagrantfile for local experimentation.

The version matrix, and which entry is the default

The support table is unusually wide, and the documentation marks the default choice in bold, which is worth reading carefully before you pick a version.

Architectures are amd64 and arm64. Container runtimes are Docker and containerd, with containerd as the default. Network plugins are flannel and calico, with calico as the default. The kube-apiserver load balancer options are slb, haproxy and nginx, with nginx as the default. The ingress controller is nginx-ingress. The bundled etcd is 3.5.21-0.

Kubernetes versions run from v1.20 through v1.33, with v1.33 as the default, and the default branch of the repository is named release-1.33 to match. The branch naming convention is stated: a release-* branch installs that version of Kubernetes, and the develop branch is the development branch, which the documentation says is not recommended for use.

Operating systems are listed with their versions. RedHat 7, Rocky Linux 8 and 9, CentOS 7.9 and 8, Debian 11 and 12, Ubuntu 20.04, Kylin V10, Anolis OS 8, OpenEuler 21.09, 22.03 and 23.03, and Almalinux 8 and 9.

The breadth of the distribution list is a deliberate feature, and the project states it as one: being unaffected by domestic network restrictions, which is a direct reference to the difficulty of pulling images and packages from upstream registries and mirrors inside China. The same list of stated features covers all components being managed by kubelet, multi master high availability, mutual TLS authentication, a customisable TLS certificate validity period, RBAC authorisation, and NetworkPolicy support.

The tension in the matrix is between the wide version range and the moving parts around it, which is exactly what the known issues section warns about.

The known issue is about old versions and new plugins

There is one documented known issue, and it is specific enough to be useful.

Because plugins such as the network plugin and the ingress controller update their own versions, they may no longer be compatible with older Kubernetes versions. If you specify an old Kubernetes version during deployment, the plugin deployment can fail with an error. The advice is to install the default version of Kubernetes or the latest one, and a discussion is linked at issue 28.

This is the fundamental trade-off in the project as designed. Supporting v1.20 through v1.33 is genuinely useful, because a lot of clusters in the world are on old versions and an operator who needs to reproduce or repair one does not want to upgrade first. But the components that sit alongside the Kubernetes version, the CNI plugin and the ingress controller, are not pinned to the same release cadence, and they are the pieces that break.

The practical reading is that the wide version support matters most for the components that are already installed, where the playbooks for a node addition or a certificate renewal have to match what is already there. For a fresh install, taking the default is the lower risk path, and the documentation says so.

The other practical detail is the certificate lifecycle. Certificate renewal is a separate playbook, 92-certificates-renew.yml, and the mutual TLS authentication with a customisable validity period is a stated feature, which means the renewal path is part of the intended workflow rather than an afterthought. The documentation index also has a dedicated page for certificate rotation.

Ten documentation pages covering the whole lifecycle

The documentation index is a numbered list of guides in Chinese, and reading the titles tells you what the project considers the complete lifecycle of a cluster.

The first five cover setup and running: installation notes, cluster installation, node management, certificate rotation and cluster upgrade. The next group covers the operations that separate a demo from a production install: cluster backup, cluster restore, cluster reset, offline installation and further reading.

The offline installation guide is the one that pairs with the stated feature about not being affected by domestic network restrictions. Installing Kubernetes normally means pulling a set of container images, and in an environment with restricted or slow access to the upstream registries, that is the step that fails. A guide dedicated to offline installation means the project treats a disconnected or restricted network as a supported case rather than an edge case, and the offline/ directory at the repository root holds the artefacts for it.

The backup and restore pair deserves a note. Many installation tools treat backup as an afterthought, and a cluster that cannot be restored is a cluster you cannot safely upgrade. Here, backup and restore are separate playbooks, 93 and 94, sitting alongside reset at 99, which is the playbook that tears a cluster down for a clean rebuild.

The order of the guides also matches the order of the playbooks at the root, which makes the whole thing navigable in two directions. You can start from a task, such as adding a worker node, find the playbook, or start from a playbook and find the explanation.

There is also a recorded terminal session linked as an asciicast, which is a useful reference for what the install actually looks like when it runs rather than what the documentation says it should.

A community project with an explicit licence position

The project is a community effort, and the participants are credited by name in the readme, with avatars for carllhw, Jaywoods2, ChongmingDu, happinesslijian, zlingqu and li-sen.

The licence is the interesting part, and it is not a standard one. The badge in the readme and the badge on the top level both point at a licence labelled Anti 996, and the repository records the licence as one that GitHub cannot classify, with a LICENSE file at the root. The Anti 996 licence is a Chinese initiative aimed at prohibiting the 996 working schedule, and a project adopting it is making a statement about labour practices rather than about software reuse.

That choice has a practical consequence for anyone considering the project outside its home context. A licence that is not on the SPDX list and cannot be auto-detected requires a lawyer to read rather than a package manager to resolve, and it does not sit in the permissive set that most corporate policies allow by default. That is worth checking with whoever handles licensing in your organisation, especially since the project explicitly says it does not support the 996 schedule and is presumably enforcing that in how its contributors are treated.

The relationship to kubeasz is stated at the top of the readme. The project was inspired by kubeasz, and anyone who wants a binary based installation is pointed there. That is a useful pointer rather than a competition: kubeadm-ha uses kubeadm as its installation mechanism, kubeasz uses the component binaries directly, and the two approaches differ in how they handle upgrades and in how much control you get over the node content.

For a FOSSA badge on the readme, the project runs automated licence scanning on its dependencies, which is a reasonable practice for a project that ships Ansible roles and container images to other people's machines.

Editorial conclusion

kubeadm-ha suits a team that needs a repeatable multi master Kubernetes install without writing their own Ansible, and who want the option to stop after any single component to inspect the state. It does not suit a team that wants a managed control plane, and the older Kubernetes versions in the support matrix come with a known caveat about plugin incompatibility. Before running it, check the documented install notes, decide between the one script and the step by step playbooks, and read the known issues entry, which recommends the default or latest Kubernetes version rather than an old pinned one.

Frequently asked questions

Official sources

1. Issues
2. README
3. TimeBye/kubeadm-ha on GitHub