Kubespray — Production-Ready Kubernetes via Ansible

Introduction

Kubespray is a composition of Ansible playbooks, inventory templates, and provisioning tools that turns a list of SSH-reachable hosts into a CNCF-conformant Kubernetes cluster. It''s maintained as part of the Kubernetes project and is one of the few open-source installers that covers bare metal, OpenStack, vSphere, AWS, Azure, GCP, and Oracle Cloud from a single codebase.

What Kubespray Does

• Bootstraps etcd, control-plane, and worker nodes with HA options (stacked or external etcd, kube-vip, MetalLB).
• Installs a wide choice of CNI plugins: Calico, Cilium, Flannel, Weave, Kube-OVN, Canal, Multus.
• Configures container runtime (containerd, CRI-O, or Docker) and hardens kernel/sysctl settings.
• Applies upgrade, scale, remove-node, and reset playbooks for the full cluster lifecycle.
• Ships add-ons: CoreDNS, Metrics Server, ingress-nginx, Cert-Manager, Registry, Local Path Provisioner.

Architecture Overview

The project is pure Ansible: roles under roles/ compose a set of playbooks (cluster.yml, upgrade-cluster.yml, scale.yml, remove-node.yml, reset.yml). Inventory drives everything — host groups (kube_control_plane, etcd, kube_node) map to role execution. Templating uses Jinja2 with per-release variables pinned by kube_version, making version skew and offline installs reproducible. Terraform modules under contrib/terraform/ can provision the infrastructure before the playbook phase.

Self-Hosting & Configuration

• Run from a control host with Python 3.10+ and Ansible 2.16+; target nodes only need SSH and Python.
• Customize via inventory/<cluster>/group_vars/ — network plugin, pod/service CIDRs, cloud provider, audit logs.
• For air-gapped sites, mirror images and binaries to a private registry and set registry_host + kube_image_repo.
• Use upgrade-cluster.yml with kube_version=v1.30.3 to perform controlled, minor-version bumps.
• Enable addons selectively: ingress_nginx_enabled, metrics_server_enabled, cert_manager_enabled.

Key Features

• Multi-platform: deploys on CentOS/RHEL/Rocky, Ubuntu, Debian, Flatcar, Amazon Linux, openSUSE.
• HA control plane with kube-vip or external load balancer and stacked or external etcd topologies.
• Pluggable CNI catalogue with sane defaults, plus Cilium eBPF and kube-router options.
• Rolling upgrades, in-place node reset, and automated certificate renewal.
• Strong community + SIG ownership; new Kubernetes minor versions land quickly after release.

Comparison with Similar Tools

• kubeadm — the underlying bootstrap tool; Kubespray wraps it with HA, CNI, and lifecycle playbooks.
• kOps — declarative AWS/GCP focus; Kubespray is broader but less cloud-native in provisioning.
• Rancher RKE2/RKE — great for Rancher-managed fleets; Kubespray is vendor-neutral and Ansible-idiomatic.
• Cluster API — Kubernetes-managing-Kubernetes; Kubespray suits day-one bare metal installs without management clusters.
• k3s/k0s installers — lightweight single-binary distros; Kubespray targets full upstream Kubernetes conformance.

FAQ

Q: Can I install an offline/air-gapped cluster? A: Yes. Kubespray documents a full offline workflow using a local OCI registry and an HTTP artifact mirror.

Q: How do I add or remove a node? A: Edit the inventory and run scale.yml to add nodes or remove-node.yml -e node=<name> to drain and remove.

Q: Which CNI is the default? A: Calico, but you can switch by setting kube_network_plugin: cilium (or flannel, kube-ovn, weave) in group vars.

Q: Does it support ARM64? A: Yes, most CNIs and container runtimes have arm64 images; Kubespray has first-class Raspberry Pi / Ampere support.

Sources

• https://github.com/kubernetes-sigs/kubespray
• https://kubespray.io