Kubean: driving kubespray cluster installs from inside Kubernetes

A manager cluster that installs the clusters

Kubean is described as a production ready cluster lifecycle management toolchain based on kubespray and other cluster LCM engines. The important word in that sentence is toolchain, not a replacement.

The architecture has two sides. On one side there is kubespray, the well known Ansible based installer that the readme links to the kubernetes-sigs repository, plus other cluster lifecycle engines. On the other side there is Kubean itself, which is a Go project whose job is to make those engines callable from inside a Kubernetes cluster. The repository layout confirms the split: there is a playbooks/ directory for the Ansible side, an api/ directory, pkg/ and cmd/ for the Go operator, charts/ for the Helm chart, and artifacts/ for the offline packages.

So the operating model is that you have a management cluster, the kubean-operator runs inside it, and you describe cluster operations as Kubernetes objects. The feature list puts it as deploying of Kubean and lifecycle management of kubernetes cluster implemented by a declarative API.

That is the specific problem it solves. Kubespray on its own is a command line tool you run against a set of hosts, which works well for a one-off bootstrap but does not fit a platform team that wants every cluster operation to be a reviewable, auditable, versioned API object. Kubean puts the declarative layer on top of an installer that already knows how to configure a cluster properly.

It is a Cloud Native Computing Foundation sandbox project, which the readme states with the CNCF artwork, and it also carries a Kubernetes conformance certified badge in the header.

The offline packages are the reason to care

One feature in the list deserves more attention than the others, because it is the one that distinguishes this kind of tool from a convenience wrapper.

Offline supported. The readme explains that offline packages, meaning os packages, images and binaries, are released with the release, and that you will not have to worry about how to gather all the resources you need.

That is a serious requirement to solve. A kubespray run needs an inventory of hosts, a set of Ansible roles, container images for every node component, and a base OS package set per distribution. In a network-restricted environment, an air gapped install is a substantial engineering project in itself. Shipping those artefacts alongside the release turns that from a project into a download.

The artifacts/ directory in the repository root is where this lives, and the Makefile has a spray tag variable, SPRAY_TAG, which defaults to latest, indicating that the spray job image version is selectable rather than hardcoded.

The other two features in the list are about reach rather than novelty. Compatibility covers multi-arch delivery, supporting AMD and ARM with common Linux distributions, and also includes Kunpeng with Kylin, which tells you the project cares about architectures and distributions outside the usual x86 Linux default. Expandability allows custom actions to be added to a cluster without any changes for Kubespray, which is the extension point that lets a platform team keep their site specific configuration out of the upstream installer.

Installing the operator with Helm

The local install path is documented in three steps, and the first is a prerequisite rather than a command: you need a Kubernetes cluster running with Helm installed on it. That management cluster is where the operator lives, and it is separate from the clusters it will later create.

The operator goes in with a Helm chart from the project's own repository.

   helm repo add kubean-io https://kubean-io.github.io/kubean-helm-chart/
   helm install kubean kubean-io/kubean --create-namespace -n kubean-system

Note the namespace, kubean-system, which is also where the later job status checks look. The install creates the namespace for you with the create-namespace flag, so the operator and everything it schedules lives in one place.

The check afterwards is a plain pod listing in that namespace.

   kubectl get pods -n kubean-system

There are two other installation routes described in the readme. One is a scenario on Killercoda, an online platform for interactive technique learning, which is the fastest way to see the thing work without touching your own cluster. The other is a guided installation mission in the KubeStellar Console, which offers step-by-step instructions, pre-flight checks, validation, troubleshooting tips and rollback support for Kubean specifically.

That second option is worth a note. A guided mission with rollback support implies the project expects people to install the operator into clusters they care about, not only into test environments.

Installing a first cluster with the minimal example

The third step of the quick start deploys an all-in-one cluster with minimal configuration, and the workflow shows the declarative model in action.

You start from a prepared example, the AllInOne.yml file in examples/install/1.minimal, and replace the placeholder strings, with the readme naming IP1 and USERNAME as examples of what needs substituting for actual values.

Then you apply it, and that is what starts the kubespray job.

      kubectl apply -f examples/install/1.minimal

The result is a Job, because that is how the kubespray work is executed.

      kubectl get job -n kubean-system

So the whole install of a Kubernetes cluster reduces to applying a YAML file and watching a job. The cluster is created by an operator running inside another cluster, and the declarative object is the durable record of what was requested.

The examples directory shows the wider set of operations that are available: debug, install, scale, uninstall and upgrade. Scale and upgrade are the interesting ones from an operational standpoint, since they are the operations a platform team runs repeatedly rather than once, and a declarative API is a better fit for a repeatable, reviewable operation than an Ansible invocation typed into a terminal.

The operator's Go code is built on controller-runtime, with the k8s.io api, apimachinery, apiserver, client-go and component-base modules all at v0.35.0, and cobra and pflag for the command line. The api/ directory has its own Makefile, and the top level update target runs that API update, then go mod tidy, then go mod vendor, so the API types, the module file and the vendor directory are kept in step in one command.

The compatibility table is the real documentation

The readme contains a table of Kubean version against supported Kubernetes versions, default Kubernetes version, and the kubespray SHA it pins. It is the most informative thing in the document.

The current rows run from v0.34.2 down to v0.22.5. The newest, v0.34.2, supports Kubernetes v1.33 through v1.35 with v1.34.7 as the default, against kubespray SHA a254f5e. Going back, v0.33.2 covers the same v1.33 to v1.35 range with v1.33.8 as the default and SHA e3b5c41. v0.32.4 and v0.31.0 and v0.30.2 cover v1.32 to v1.34 with v1.32.9 default, and the older rows step down through v1.31 to v1.33 with v1.32.9 and v1.31.6 defaults.

Two things follow from reading it carefully. First, each Kubean release supports a window of about three Kubernetes minor versions rather than a single one, and the default sits in the middle of that window, which is a sensible pinning policy. Second, the kubespray SHA is recorded per release, which means the exact upstream installer state is traceable for any Kubean version you are running. That is what you need in order to reason about a change in behaviour between two Kubean releases.

The table also shows the release history has been steady: from v0.22.5 up through v0.34.2, the readme records a release for every increment, and the recent tags listed separately are v0.39.2 from 2026-10-13, v0.39.1 from 2026-09-29 and v0.39.0 from 2026-09-24. The last push was on 2026-10-20.

A note for readers: the link to the supported Kubernetes versions list points at a path under docs/zh, so the Chinese directory of the documentation, and the readme itself is offered in both English and Chinese with a link to README_zh.md at the top.

The Python version check that bites people on RHEL and Kylin

There is a warning above the quick start, and it is the kind of detail that saves a deployment.

The readme says to check Python compatibility before deployment, because the two spray-job image variants have different requirements, and points at a documentation page on Python versions and image selection, calling out RHEL 8 and Kylin V10 in particular.

This is a direct consequence of the architecture. The kubespray work runs as a job, and the image variant you run determines which Python it gets. Pick the wrong one and the job fails, possibly well into the install, after the operator has already scheduled work against your hosts.

The Makefile carries the same philosophy for versioning. It derives the version from git describe --tags with a fallback to unknown when tags are missing, which the comment explains is for a forked repository that does not sync tags from upstream, and then converts the git description into a semver for the image tag and into a chart version by stripping the leading v.

So the project is consistent about pinning: the kubespray SHA per Kubean release, the Python image variant for the spray job, and a chart version derived from the same source as the binary. Each of those is a place where a floating dependency would eventually produce a cluster that differs from the one you tested.

Where Kubean is the wrong tool

The boundaries are clear, and they follow from what Kubean is layered on top of.

The first is that you need a management cluster before you can have managed clusters. Kubean runs inside Kubernetes and creates other Kubernetes clusters, so if you are a single-cluster shop with one cluster and no plans for more, the overhead is not justified. The requirement of a running cluster with Helm installed is right there in the first step of the local install.

The second is the platform assumption inherited from kubespray. Kubespray installs clusters on bare metal or virtual machines that you control, over SSH, with an inventory. That is a different model from a managed cloud service where the provider's API provisions the infrastructure. If your clusters come from a cloud's managed Kubernetes offering, a declarative operator over that is solving a problem you do not have, and the cloud's own tooling is the simpler answer.

The third is the operational weight of the pattern based approach underneath. A declarative operator that runs Ansible means your cluster configuration is expressed as playbooks and inventory, and the debugging tools you already know apply. The benefit is reviewability and repeatability, and the cost is a layer between you and the installer, so when a job fails you have to look at the operator's logs, the job logs and the underlying play output.

The fourth is the release compatibility window. Each Kubean version supports a range of Kubernetes minor versions and a specific kubespray SHA, so upgrading Kubean is a decision with a support horizon attached, and the readme's table is the thing you have to consult before every upgrade rather than a version number you can treat as floating.

On the alternative, the difference in approach against plain kubespray is exactly the declarative layer. Running kubespray directly from a workstation or a CI job against an inventory is simpler, has one fewer component, and leaves you with a log rather than a Kubernetes object. Kubean gives you a cluster operation as a custom resource, which means it can be stored, diffed, reviewed in a pull request, observed with the same tooling as everything else in the cluster, and driven by a controller rather than a human. The trade is that the second option is a platform engineering investment, and it pays off when you are provisioning clusters repeatedly and to a schedule rather than occasionally by hand.

Editorial conclusion

Kubean suits a platform team that already runs Kubernetes and wants to describe cluster lifecycle operations as versioned API objects instead of ad hoc Ansible runs, and it does not suit a single-cluster user or a team that needs clusters on clouds Kubean does not support, because the underlying engine is kubespray and the platform assumptions are its own. Before you adopt it, read the compatibility table for the Kubean version you plan to pin and confirm the Kubernetes range and the kubespray SHA line up with your target, and check the Python compatibility notes for the two spray-job image variants if you deploy on RHEL 8 or Kylin V10.

Frequently asked questions

Official sources

1. kubean-io/kubean on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases