Instructions for setting up a Kubernetes cluster.

Edit This Page

Installing Kubernetes On-premises/Cloud Providers with Kubespray


This quickstart helps to install a Kubernetes cluster hosted on GCE, Azure, OpenStack, AWS, or Baremetal with Kubespray.

Kubespray is a composition of Ansible playbooks, inventory, provisioning tools, and domain knowledge for generic OS/Kubernetes clusters configuration management tasks. Kubespray provides:

To choose a tool which best fits your use case, read this comparison to kubeadm and kops.

Creating a cluster

(1/5) Meet the underlay requirements

Provision servers with the following requirements:

Kubespray provides the following utilities to help provision your environment:

Note: kubespray-cli is no longer actively maintained. {. :note}

(2/5) Compose an inventory file

After you provision your servers, create an inventory file for Ansible. You can do this manually or via a dynamic inventory script. For more information, see “Building your own inventory”.

(3/5) Plan your cluster deployment

Kubespray provides the ability to customize many aspects of the deployment:

Kubespray customizations can be made to a variable file. If you are just getting started with Kubespray, consider using the Kubespray defaults to deploy your cluster and explore Kubernetes.

(4/5) Deploy a Cluster

Next, deploy your cluster with one of two methods:

Note: kubespray-cli is no longer actively maintained.

Both methods run the default cluster definition file.

Large deployments (100+ nodes) may require specific adjustments for best results.

(5/5) Verify the deployment

Kubespray provides a way to verify inter-pod connectivity and DNS resolve with Netchecker. Netchecker ensures the netchecker-agents pods can resolve DNS requests and ping each over within the default namespace. Those pods mimic similar behavior of the rest of the workloads and serve as cluster health indicators.

Cluster operations

Kubespray provides additional playbooks to manage your cluster: scale and upgrade.

Scale your cluster

You can scale your cluster by running the scale playbook. For more information, see “Adding nodes”.

Upgrade your cluster

You can upgrade your cluster by running the upgrade-cluster playbook. For more information, see “Upgrades”.

What’s next

Check out planned work on Kubespray’s roadmap.


You can reset your nodes and wipe out all components installed with Kubespray via the reset playbook.

Caution: When running the reset playbook, be sure not to accidentally target your production cluster!



Create an Issue Edit this Page