Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français

Kubespray: when to choose it over kubeadm

By updated

Improve this page

Logo Kubernetes

Kubespray is a collection of Ansible playbooks that installs Kubernetes on machines you already provide, relying on kubeadm underneath. Choose it when your team already automates its servers with Ansible and you want a repeatable cluster on ordinary Linux machines, without changing operating system or way of working. Do not choose it to learn Kubernetes or to pass the CKA: kubeadm is a better fit. This page helps you decide, shows the installation in a few commands, and explains what the tool changes day to day.

What you will learn

  • Recognize what Kubespray automates, and what remains your responsibility
  • Compare Kubespray with kubeadm, RKE2, k0s and Talos
  • Choose Kubespray, or rule it out, based on your team, your fleet and the target Kubernetes version
  • Spot what Kubespray changes for upgrading, adding and removing nodes

What does Kubespray solve, and how does it work?

Kubespray solves a repetition problem: installing Kubernetes with kubeadm means typing the same commands on every machine, in the right order, and starting over for every new node. Kubespray writes that sequence once as Ansible playbooks, then runs it from your workstation on all the machines over SSH.

Kubespray is not a Kubernetes distribution. It ships no binary and no operating system of its own: it prepares the nodes' system, downloads the components (etcd, kubelet, kubeadm, container runtime, network plugin), then calls kubeadm to form the cluster. The Kubernetes you get is therefore the kubeadm one, installed without you typing each command.

Everything Kubespray knows about your cluster lives in the Ansible inventory, the file that lists your machines and their role. It expects three groups of machines, with fixed names: kube_control_plane for the nodes that run the control plane, etcd for the members of the cluster's database, and kube_node for the workers. Two special groups also exist, calico_rr and bastion, useful in particular cases. The cluster variables (version, network plugin, address ranges) are set in inventory/mycluster/group_vars/.

Kubespray does not provision the machines, does not configure your firewalls and does not set up access for you. According to its README, the nodes must allow IPv4 forwarding (net.ipv4.ip_forward), reach the Internet (or have a mirror in an offline environment), and the SSH account must be able to become root. Firewalls are not managed: the project advises disabling them during the deployment or opening the ports yourself.

When should you choose Kubespray, and when should you avoid it?

Choose Kubespray when three conditions are met: you have ordinary Linux machines to manage (bare metal, virtual machines or cloud), a team that can already read and write Ansible, and a need to replay the same operations on several clusters. In that case the tool fits existing habits: a versioned inventory, the project's playbooks, the same mechanisms as for the rest of the fleet.

Rule it out in four situations. If you want to learn or pass the CKA, kubeadm remains preferable: the exam expects commands typed by hand, and Kubespray hides them behind Ansible. If your team does not know Ansible, it will have to learn it to understand a deployment that fails. If you want an operating system without a shell or SSH, that is the Talos model, not the Kubespray one. Finally, if you must install the latest Kubernetes version as soon as it ships, read the section on the installed version below first.

The table compares the five options in this module on the criteria that most often decide the choice. kubeadm is the reference point: it is the upstream tool, and the course has you practice it.

CriterionkubeadmKubesprayRKE2k0sTalos
What it isUpstream bootstrap toolAnsible playbooks that drive kubeadmDistribution shipped with its own choicesSingle-binary distributionOperating system dedicated to Kubernetes
MachinesLinux of your choiceLinux of your choiceLinux of your choiceLinux of your choiceTalos only, with no SSH or shell
AutomationYou write it yourselfAnsible, includedInstall script, then your own toolk0sctl and a YAML filetalosctl and an API
Default networkNone, to be installedCalicoCanalkube-routerFlannel
Skills requiredKubernetesKubernetes and AnsibleKubernetes and RKE2Kubernetes and k0sKubernetes and Talos
Good choice forLearning, the CKA, a custom clusterA fleet managed with AnsibleSecurity and compliance (CIS profile)Edge, CI, small clustersA new fleet, with no system administration

k3s (in French), which the site covers separately, is the lightweight distribution for the edge and developer workstations, with Flannel by default. The guide Deploy a Kubernetes cluster in production covers the whole landscape, including managed services.

Which Kubernetes version does Kubespray install?

The latest release, Kubespray v2.32.0, dates from 22 September 2026. Its README ("Supported Components" section) gives Kubernetes 1.36.4 as the version installed by default, with etcd 3.6.14, containerd 2.3.5 and Calico 3.31.7. Checked on 2026-11-13 against the release notes and the README of the v2.32.0 tag.

This course teaches Kubernetes 1.37, so by default Kubespray installs one minor version behind. That lag is bearable, since Kubernetes maintains several minor versions in parallel, but it matters if a requirement forces you onto 1.37. RKE2 (v1.37.2+rke2r1, published on 5 November), k0s (v1.37.2+k0s.1, on 6 November) and Talos (Kubernetes 1.37.1 by default) already ship 1.37. Always check the README of the tag you plan to use before you commit.

Two other points of v2.32.0 weigh on the choice. The first concerns Ansible: the release requires ansible-core 2.19.x. Its urgent upgrade notes ask you to recreate the Python environment from its requirements.txt (Ansible 12.3.0), and flag behavior changes in conditions and templates, including variables passed with -e. A team that manages its Ansible separately must therefore plan an environment dedicated to Kubespray.

The second concerns operating systems. The release matrix covers in particular Debian 12 and 13, Ubuntu 22.04, 24.04 and 26.04, and Rocky Linux 9 and 10 (10 in experimental mode). Check that your machines are listed before choosing the tool.

What does an installation with Kubespray look like?

The demonstration below follows the commands of the official documentation, Getting started and Installing Ansible. It is not replayed for this page and is not graded: it is there to show the shape of the procedure. To practice installing a cluster, follow the kubeadm lesson.

The control workstation first prepares a dedicated Python environment. The versions of Ansible and its dependencies are pinned in the project's requirements.txt, and each release is only tested with them. Work from a tagged release, never from the master branch.

Terminal window
git clone https://github.com/kubernetes-sigs/kubespray.git \
--depth 1 --branch v2.32.0
cd kubespray
python3 -m venv kubespray-venv
source kubespray-venv/bin/activate
pip install -r requirements.txt

The inventory then describes the machines. This example, inspired by the project's inventory/sample/inventory.ini file, declares one control plane node that also runs etcd, and two workers. The addresses are those of your network.

inventory/mycluster/inventory.ini
[kube_control_plane]
cp1 ansible_host=192.168.122.50 ip=192.168.122.50 etcd_member_name=etcd1
[etcd:children]
kube_control_plane
[kube_node]
worker1 ansible_host=192.168.122.51 ip=192.168.122.51
worker2 ansible_host=192.168.122.52 ip=192.168.122.52

A single control plane node does not hold up in production: the project's sample inventory describes three control plane nodes with stacked etcd, that is, on the same machines. The High availability lesson explains this topology.

The deployment finally runs through a single playbook, cluster.yml. It prepares the nodes, installs etcd, initializes the control plane with kubeadm, joins the workers and sets up the network plugin.

Terminal window
ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml -b -v \
--private-key=~/.ssh/private_key

At the end, look at the Ansible summary (PLAY RECAP): it must show failed=0 and unreachable=0 for every machine. That proves the playbooks ran, not that the cluster works. You still need to fetch the kubeconfig and check that the nodes are Ready with kubectl get nodes. With kubeconfig_localhost enabled, Kubespray drops admin.conf into inventory/mycluster/artifacts/. The documentation specifies that the server address there may be a private IP: if your workstation cannot reach it, replace it with the address of a control plane node or of the load balancer.

What does Kubespray change for operations?

With kubeadm, you change the cluster by typing commands on the nodes. With Kubespray, you change the inventory or the variables, then you replay a playbook. Each operation has its own, and none is carried out by hand on the machines without the inventory knowing about it.

To add a worker, you declare the machine in the inventory then run scale.yml. To remove a node, remove-node.yml (with --extra-vars "node=<name>") drains the node, resets it, then removes it from the cluster. A plain kubectl delete node does not clean the machine. The project specifies that this playbook does not remove the first control plane node or the first etcd node.

The upgrade goes through upgrade-cluster.yml, which cordons, drains and reintegrates the nodes in batches after you change kube_version. By default a batch is 20% of the nodes, and serial=1 processes them one at a time. The documentation warns that a direct jump from an old Kubespray release to the latest is not supported: the upgrade moves one tag at a time, without skipping a minor version, reading the notes of each. Your upgrade calendar therefore depends on Kubespray's pace as much as on Kubernetes'. The lesson Upgrade a Kubernetes cluster covers the general case.

For high availability, Kubespray installs by default an nginx proxy on each worker, which spreads the calls across the API servers (loadbalancer_apiserver_localhost). This avoids an external load balancer, at the cost of extra health checks on each API server. A dedicated load balancer or kube-vip remains possible.

Finally, troubleshooting moves. When a deployment fails, Ansible points to the task and the machine at fault: the first reflex is to read that task, not to dig through the kubelet logs. That is an asset for a team that already reads Ansible, and a drag for one that does not.

Key takeaways

  • Kubespray installs Kubernetes with Ansible playbooks that drive kubeadm on machines that are already ready; it is not a distribution.
  • It suits a team that already automates with Ansible and manages a fleet of ordinary Linux machines.
  • To learn Kubernetes or pass the CKA, kubeadm remains the right choice.
  • The three inventory groups, kube_control_plane, etcd and kube_node, alone describe the cluster topology.
  • v2.32.0 (22 September 2026) installs Kubernetes 1.36.4 by default, one minor version behind the 1.37 taught here.
  • It requires ansible-core 2.19: plan a dedicated Python environment.
  • Adding, removing or upgrading a node goes through the scale.yml, remove-node.yml and upgrade-cluster.yml playbooks.
  • Do not skip a minor version of Kubespray: the upgrade moves one tag at a time.

Test your knowledge

Seven questions on what sets Kubespray apart from the other solutions: what it automates, what it leaves to you, the version it installs and how it changes operations.

Knowledge check

Check what you have learned with this interactive quiz

7 questions
5 min
80% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer