kubeasz: Ansible-Based Kubernetes Deployment Without the Network Headaches

What kubeasz Solves and Who It Is For

Most Kubernetes installers hide the control plane behind a single binary or a hosted service. kubeasz takes the opposite route. The README describes it as a tool for deploying high-availability k8s clusters that also aims to serve as a reference book for k8s practice and usage. Deployment is binary-based, automated through ansible-playbook, and the project offers both a one-click install script and a step-by-step installation guide for installing each component separately.

The target user is an operations engineer or platform engineer who wants to see and configure every part. The README states that kubeasz assembles a complete cluster from each individual component and provides the most flexible configuration capability, with the ability to set nearly any parameter of any component, while still shipping a set of working default configurations. That combination matters: a team can start with defaults and later override a single etcd or kube-apiserver parameter without rebuilding the whole deployment model.

The stated design goal about network conditions is the second differentiator. The repository description says the tool is not affected by the domestic network environment, and the README lists offline installation as a cluster feature. For anyone who has watched a kubeadm join hang on an image pull from a registry that is slow or blocked, that constraint alone explains the project's existence.

How kubeasz Assembles a Cluster from Binary Components

There is no single kubeasz daemon. The repository layout shows the mechanism directly: a playbooks directory, a roles directory, manifests, an ezctl script, an ezdown script, and an ansible.cfg at the top level. The work is done by Ansible roles applied to hosts you declare in an inventory file.

The example directory contains three files that define the shape of a deployment: example/config.yml, example/hosts.allinone, and example/hosts.multi-node. The inventory files list machines and assign them roles such as master, node, or etcd. The config file holds cluster-wide settings. Running the playbooks against that inventory produces the cluster.

The installation guide is split into numbered stages that mirror the actual data flow: create certificates and install prerequisites, install the etcd cluster, install the container runtime, install master nodes, install node nodes, install the network plugin, then install cluster addons. Each stage is a separate document, which means a failure at the etcd stage can be debugged without rerunning the control plane steps.

The runtime is containerd, listed at v2.3.x in the README. Kubernetes versions covered are v1.33, v1.34, v1.35, and v1.36. Networking is not baked in: calico, cilium, flannel, kube-ovn, and kube-router all have their own setup documents. The README also notes that the project can automatically create a BGP Route Reflector network mode suitable for large-scale clusters, which is a Calico-specific topology rather than a general default.

Installing kubeasz and Running a First All-in-One Cluster

The README points to docs/setup/quickStart.md for a single-machine test environment called AllinOne deployment. That is the intended first contact, not a production path.

kubeasz can also run from a container. The Dockerfile builds on easzlab/ansible:2.14.4-lite, copies the repository to /etc/kubeasz, and symlinks the two control scripts into the PATH:

FROM easzlab/ansible:2.14.4-lite
ENV TZ="Asia/Shanghai"
COPY . /etc/kubeasz
RUN set -x \
    && ln -s -f /etc/kubeasz/ezctl /usr/bin/ezctl \
    && ln -s -f /etc/kubeasz/ezdown /usr/bin/ezdown

After that image is built, ezctl and ezdown are available as commands inside the container. The ezdown script is the one associated with downloading the binary packages and offline resources; the README's offline installation document is the reference for that workflow.

The inventory and configuration come from the example directory. The README does not print the exact copy commands, so treat the file names as the contract: example/hosts.multi-node defines your machines, example/config.yml defines cluster settings. The numbered guide then walks through certificate creation, etcd, the container runtime, masters, nodes, the network plugin, and addons in that order.

Where kubeasz Gets in the Way

The flexibility is the cost. Because kubeasz exposes nearly every component parameter, the surface area for a misconfiguration is large, and the failure will often surface several stages later. A wrong etcd peer address in the inventory may only appear when the control plane tries to reach it.

The supported operating system list is explicit and finite: Alibaba Linux 3.2104, Alma Linux 8 and 9, Anolis OS 8.x in both RHCK and ANCK variants, RHEL 8 and 9, Debian 12 and 13, Fedora 36 and 37, Kylin Linux Advanced Server V10 across Tercel, Lance, and Halberd, openEuler 22.03 LTS and 24.03 LTS, openSUSE Leap 15.x, Rocky Linux 8 and 9, and Ubuntu 22.04 and 24.04. The README adds that most systemd-based distributions can work, and directs users with problems to docs/setup/multi_os.md. That is a soft promise, not a tested guarantee. If you run something outside the list, you are the one validating it.

The project is not a lifecycle manager. The README's cluster management section covers adding and removing nodes, managing master and etcd nodes, upgrading the cluster, and backup and restore. There is no mention of autoscaling, no hosted control plane, and no web console in the core repository. If your team expects a dashboard by default, note that headlamp appears only as an optional plugin in the usage guide.

Finally, the licence situation deserves a direct look. The README's copyright line states Apache License 2.0 and points to docs/mixes/LICENSE, but the repository metadata provided does not carry a detected licence identifier. Read the LICENSE file in the repository before you rely on the terms.

kubeasz Compared with Kubespray

The nearest comparison in the related searches is Kubespray, and the difference is in what each tool treats as the unit of deployment.

Kubespray is also Ansible-based, but it deploys Kubernetes through kubeadm and container images. The related searches include Kubespray air gap installation and Kubespray etcd, which suggests users hit the same two concerns there: working without internet access and understanding the etcd layer.

kubeasz deploys from binaries and exposes the etcd installation as its own numbered stage in the guide. That makes the etcd topology, certificates, and startup parameters visible in the playbook rather than hidden behind kubeadm's configuration file. Whether that is better depends on what you want to debug. If you prefer kubeadm's opinionated defaults and its upgrade path, Kubespray is the closer fit. If you want to read and modify the actual component configuration, kubeasz puts it in front of you.

The network plugin story differs too. kubeasz documents calico, cilium, flannel, kube-ovn, and kube-router as first-class choices with separate setup documents, plus the automated BGP Route Reflector mode for Calico. A cluster running kube-router or kube-ovn is a configuration choice made at install time, not an add-on bolted on afterward.

Editorial conclusion

kubeasz fits operators who want to assemble Kubernetes from binary components with Ansible, especially in environments where pulling container images from the public internet is unreliable or forbidden. Teams that want a managed control plane, automatic node scaling, or a GUI should look elsewhere. Before committing, verify your target OS appears in the supported list, confirm the kubeasz version matches your intended Kubernetes version in the compatibility table, and read the planning document at docs/setup/00-planning_and_overall_intro.md.

Frequently asked questions

Official sources

1. easzlab/kubeasz on GitHub
2. Issues
3. Project website
4. README
5. Releases