Kubespray: Ansible-based Kubernetes cluster deployment
Production-grade Kubernetes deployment via Ansible playbooks.
Learn more about kubespray
Kubespray is a deployment tool built on Ansible that provisions and configures Kubernetes clusters from scratch. It uses Ansible playbooks to orchestrate cluster setup across bare metal, cloud providers (AWS, GCE, Azure, OpenStack, vSphere, Equinix Metal), and other infrastructure platforms. The tool supports multiple Linux distributions including Debian, Ubuntu, CentOS/RHEL, Fedora, and others, with configurable components for container runtimes (Docker, containerd, CRI-O) and networking solutions. Common deployment scenarios include setting up highly available production clusters, air-gapped installations, and multi-node Kubernetes environments across heterogeneous infrastructure.
Infrastructure-Agnostic Deployment
Single Ansible playbook set deploys across bare metal, AWS, GCE, Azure, OpenStack, and vSphere without infrastructure-specific tooling. Eliminates the need to maintain separate deployment pipelines for heterogeneous environments.
Composable Component Architecture
Configure network plugins, container runtimes, and cluster components through Ansible variables without modifying core playbooks. Swap between containerd, CRI-O, or Docker and choose from multiple CNI providers using declarative configuration.
Broad OS Compatibility
Deploys Kubernetes clusters on multiple Linux distributions including Ubuntu, CentOS, Rocky Linux, and Debian. Unified playbooks adapt to distribution-specific package managers and init systems automatically.
from ansible import context
from ansible.executor.playbook_executor import PlaybookExecutor
from ansible.inventory.manager import InventoryManager
from ansible.parsing.dataloader import DataLoader
from ansible.vars.manager import VariableManager
loader = DataLoader()
inventory = InventoryManager(loader=loader, sources='inventory/mycluster/inventory.ini')
variable_manager = VariableManager(loader=loader, inventory=inventory)
executor = PlaybookExecutor(playbooks=['cluster.yml'], inventory=inventory, variable_manager=variable_manager, loader=loader, passwords={})
executor.run()Breaking changes: CoreDNS no longer schedules to control-plane by default, /etc/hosts no longer populated with all nodes, Weave plugin removed, 'master' tag replaced by 'control-plane'.
- –Set coredns_affinity explicitly if you need CoreDNS on control-plane nodes; default affinity changed to match upstream.
- –Replace all 'master' inventory tags with 'control-plane'; CRI-O on Ubuntu 20.04 and conntrack_modules variable are dropped.
Patch release fixing Cilium upgrade breakage from v2.27, etcd node addition failures, and kube-apiserver certificate SAN gaps.
- –Apply this release to fix Cilium clusters broken after upgrading from Kubespray 2.27 to 2.28.
- –Verify etcd node additions succeed and kube-apiserver certificates include all required SAN addresses.
Patch release upgrading ingress-nginx to v1.12.1 to fix CVE-2025-1974 and other critical vulnerabilities; includes kubeadm upgrade fixes for control plane reconfiguration.
- –Upgrade ingress-nginx to v1.12.1 immediately to resolve CVE-2025-1974 and related critical security issues.
- –Control plane upgrades now use kubeadm v1beta4 UpgradeConfiguration and run `kubeadm upgrade node` on secondary nodes.
See how people are using kubespray
Top in Cloud & DevOps
Related Repositories
Discover similar tools and frameworks used by developers
configure-aws-credentials
GitHub Action for AWS credential resolution in workflows.
setup-node
Node.js version management and dependency caching for workflows.
OpenZFS
Production-ready, enterprise-grade filesystem combining volume management, data integrity protection, snapshots, and compression for Linux, FreeBSD, and illumos systems.
awx
Django-based control plane for centralized Ansible management.
OpenLens
Community-built Kubernetes IDE without authentication requirements.