< img height="1" width="1" style="display:none;" alt="" src="https://px.ads.linkedin.com/collect/?pid=3131724&fmt=gif" />


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 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 https://get-kk.kubesphere.io | VERSION=v3.0.13 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 https://get-kk.kubesphere.io | VERSION=v3.0.13 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 of KubeKey. You can change the version number in the command to download a specific version.

Support Matrix

If you want to use KubeKey to install both Kubernetes and KubeSphere 3.4, see the following table of all supported Kubernetes versions.

KubeSphere versionSupported Kubernetes versions
v3.4.1v1.21.x, v1.22.x, v1.23.x, * v1.24.x, * v1.25.x, and * v1.26.x


  • You can also run ./kk version --show-supported-k8s to see all supported Kubernetes versions that can be installed by KubeKey.
  • The Kubernetes versions that can be installed using KubeKey are different from the Kubernetes versions supported by KubeSphere 3.4. If you want to install KubeSphere 3.4 on an existing Kubernetes cluster, your Kubernetes version must be v1.21.x, v1.22.x, v1.23.x, * v1.24.x, * v1.25.x, and * v1.26.x. For Kubernetes versions with an asterisk, some features of edge nodes may be unavailable due to incompatability. Therefore, if you want to use edge nodes, you are advised to install Kubernetes v1.23.x.

Receive the latest news, articles and updates from KubeSphere

Thanks for the feedback. If you have a specific question about how to use KubeSphere, ask it on Slack. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.