kubespray README

The project's README from github.com/kubernetes-sigs/kubespray. As one markdown file: README.md.

Deploy a Production Ready Kubernetes Cluster

Kubernetes Logo

If you have questions, check the documentation at kubespray.io and join us on the kubernetes slack, channel #kubespray. You can get your invite here

Quick Start

Below are several ways to use Kubespray to deploy a Kubernetes cluster.

Docker

Ensure you have installed Docker then

docker run --rm -it --mount type=bind,source="$(pwd)"/inventory/sample,dst=/inventory \
  --mount type=bind,source="${HOME}"/.ssh/id_rsa,dst=/root/.ssh/id_rsa \
  quay.io/kubespray/kubespray:v2.31.0 bash
# Inside the container you may now run the kubespray playbooks:
ansible-playbook -i /inventory/inventory.ini --private-key /root/.ssh/id_rsa cluster.yml

Ansible

Usage

See Getting started

Collection

See here if you wish to use this repository as an Ansible collection

Vagrant

For Vagrant we need to install Python dependencies for provisioning tasks. Check that Python and pip are installed:

python -V && pip -V

If this returns the version of the software, you're good to go. If not, download and install Python from here https://www.python.org/downloads/source/

Install Ansible according to Ansible installation guide then run the following step:

vagrant up

Documents

Supported Linux Distributions

Note:

Supported Components

Container Runtime Notes

Requirements

Hardware: These limits are safeguarded by Kubespray. Actual requirements for your workload can differ. For a sizing guide go to the Building Large Clusters guide.

Network Plugins

You can choose among ten network plugins. (default: calico, except Vagrant uses flannel)

The network plugin to use is defined by the variable kube_network_plugin. There is also an option to leverage built-in cloud provider networking instead. See also Network checker.

Ingress Plugins

Community docs and resources

Tools and projects on top of Kubespray

CI Tests

Build graphs

CI/end-to-end tests sponsored by: CNCF, Equinix Metal, OVHcloud, ELASTX.

See the test matrix for details.

kubespray (kubernetes-sigs/kubespray)

infrastructure-as-code
Searching Database…

18.8K ·GitHub
Kubespray
What is this?Kubespray is a set of Ansible playbooks that deploys a production-ready, highly available Kubernetes cluster on cloud VMs or your own bare-metal servers.
So is it a tool I install, or something else?It is not an app you install — it is a repository of Ansible playbooks and inventory you run against your servers. The repo can also be consumed as an Ansible collection.
How do I get my first cluster running?Run the playbooks from a Docker container, from a machine with Ansible installed, or spin up a local test cluster with Vagrant. The Getting started guide walks through the first deployment.
What does the machine running the deployment need?The control machine needs Ansible v2.14+, Jinja 2.11+ and python-netaddr. Target servers need a supported Linux distro and, unless you configure offline mode, internet access to pull images.
Any gotchas that could break a deployment?Kubespray does not manage firewalls — you should disable yours to avoid deployment issues. Non-root runs need the --become flag, Upstart/SysV systems are unsupported, and kernels below 4.19 need attention.
Where can the clusters run?Clusters can be deployed to AWS, GCE, Azure, OpenStack, vSphere, Equinix Metal, Oracle Cloud (experimental) or plain bare metal.
What versions and components does it deploy?Kubernetes 1.36.4 with etcd 3.6.14, plus a choice of runtime: containerd, Docker or CRI-O (experimental). Bundled extras include CoreDNS, cert-manager, Argo CD, Helm and MetalLB, along with CSI storage plugins.
How much hardware do the nodes need?The minimums are modest: 2 GB of RAM for control-plane nodes and 1 GB for workers. Actual sizing depends on your workload — there is a separate large-deployments guide.
Can I deploy a cluster without internet access?Yes, there is a dedicated Air-Gap installation guide. By default the target servers are expected to reach the internet to pull images, so offline use takes extra configuration.
Which Linux distros can be cluster nodes?Ubuntu 22.04-26.04, Debian Bookworm/Trixie, RHEL and CentOS Stream 9-10, Fedora 39-42, Flatcar, Fedora CoreOS, openSUSE, Oracle, Alma and Rocky Linux, plus several more marked experimental.
What are similar projects?kubeasz, netboot.xyz, kestra, kubernetes, vcluster, awesome-kubernetes, charts, talos
Which topics is it in?jinja, ansible, bare-metal, k8s, high-availability, infrastructure-as-code, infrastructure, aws, deployment, cloud-native, orchestration, kubernetes
Creator
kubernetes-sigs
Size
29.3 MB
Stars
18.8K
Updated
CommitOct 15Releasev2.32.0Sep 22
Age
11y
Commits · 90 Days