You are viewing documentation for KubeSphere version:v3.0.0

KubeSphere v3.0.0 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.


Developed in Go, KubeKey represents a brand-new installation tool as a replacement for the ansible-based installer used before. KubeKey provides you with flexible installation choices, as you can install Kubernetes only or install both Kubernetes and KubeSphere.

There are several scenarios to use KubeKey:

  • Install Kubernetes only;
  • Install Kubernetes and KubeSphere together in one command;
  • Scale a cluster;
  • Upgrade a cluster;
  • Install Kubernetes-related add-ons (Chart or YAML).

How Does KubeKey Work

After you download KubeKey, you use an executable called kk to perform different operations. No matter you use it to create, scale or upgrade a cluster, you must prepare a configuration file using kk beforehand. This configuration file contains basic parameters of your cluster, such as host information, network configurations (CNI plugin and Pod and Service CIDR), registry mirrors, add-ons (YAML or Chart) and pluggable component options (if you install KubeSphere). For more information, see an example configuration file.

With the configuration file in place, you execute the ./kk command with varied flags for different operations. After that, KubeKey automatically installs Docker and pulls all the necessary images for installation. When the installation is complete, you can also inspect installation logs.

Why KubeKey

  • The previous ansible-based installer has a bunch of software dependencies such as Python. KubeKey is developed in Go language to get rid of the problem in a variety of environments, making sure the installation is successful.
  • KubeKey supports multiple installation options, such as all-in-one installation, multi-node installation, and air-gapped installation.
  • KubeKey uses Kubeadm to install Kubernetes clusters on nodes in parallel as much as possible in order to reduce installation complexity and improve efficiency. It greatly saves installation time compared to the older installer.
  • KubeKey aims to install clusters as an object, i.e., CaaO.

Download KubeKey

Download KubeKey from its GitHub Release Page or use the following command directly.

curl -sfL | VERSION=v1.0.1 sh -

Run the following command first to make sure you download KubeKey from the correct zone.

export KKZONE=cn

Run the following command to download KubeKey:

curl -sfL | VERSION=v1.0.1 sh -


After you download KubeKey, if you transfer it to a new machine also with poor network connections to Googleapis, you must run export KKZONE=cn again before you proceed with the steps below.


The commands above download the latest release (v1.0.1) of KubeKey. You can change the version number in the command to download a specific version.