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.
| Criterion | kubeadm | Kubespray | RKE2 | k0s | Talos |
|---|---|---|---|---|---|
| What it is | Upstream bootstrap tool | Ansible playbooks that drive kubeadm | Distribution shipped with its own choices | Single-binary distribution | Operating system dedicated to Kubernetes |
| Machines | Linux of your choice | Linux of your choice | Linux of your choice | Linux of your choice | Talos only, with no SSH or shell |
| Automation | You write it yourself | Ansible, included | Install script, then your own tool | k0sctl and a YAML file | talosctl and an API |
| Default network | None, to be installed | Calico | Canal | kube-router | Flannel |
| Skills required | Kubernetes | Kubernetes and Ansible | Kubernetes and RKE2 | Kubernetes and k0s | Kubernetes and Talos |
| Good choice for | Learning, the CKA, a custom cluster | A fleet managed with Ansible | Security and compliance (CIS profile) | Edge, CI, small clusters | A 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.
git clone https://github.com/kubernetes-sigs/kubespray.git \ --depth 1 --branch v2.32.0cd kubespray
python3 -m venv kubespray-venvsource kubespray-venv/bin/activatepip install -r requirements.txtThe 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.
[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.51worker2 ansible_host=192.168.122.52 ip=192.168.122.52A 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.
ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml -b -v \ --private-key=~/.ssh/private_keyAt 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,etcdandkube_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-core2.19: plan a dedicated Python environment. - Adding, removing or upgrading a node goes through the
scale.yml,remove-node.ymlandupgrade-cluster.ymlplaybooks. - 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
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
Review
(0/0)Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.
Weak areas
No topic below the pass mark.
Recommended next
Hints before you try again?
Continue the course: Talos Linux: when to choose it for your Kubernetes nodes
A new full quiz with random questions
Work again only on the questions you missed