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.

Upgrade — Overview


KubeSphere v3.0.0 is compatible with Kubernetes 1.15.x, 1.16.x, 1.17.x and 1.18.x:

  • If your KubeSphere v2.1.x is installed on Kubernetes 1.15.x+, you can choose to only upgrade KubeSphere to v3.0.0 or upgrade Kubernetes (to a higher version) and KubeSphere (to v3.0.0) at the same time.

  • If your KubeSphere v2.1.x is installed on Kubernetes 1.14.x, you have to upgrade Kubernetes (to 1.15.x+) and KubeSphere (to v3.0.0 ) at the same time.


There are some significant API changes in Kubernetes 1.16.x compared with prior versions 1.14.x and 1.15.x. Refer to Deprecated APIs Removed In 1.16: Here’s What You Need To Know for more details. So if you plan to upgrade from Kubernetes 1.14.x/1.15.x to 1.16.x+, you have to migrate some of your workloads after upgrading.

Before the Upgrade


  • You are supposed to implement a simulation for the upgrade in a testing environment first. After the upgrade is successful in the testing environment and all applications are running normally, upgrade your cluster in your production environment.
  • During the upgrade process, there may be a short interruption of applications (especially for those single-replica Pods). Please arrange a reasonable period of time for your upgrade.
  • It is recommended to back up ETCD and stateful applications before upgrading in a production environment. You can use Velero to implement the backup and migrate Kubernetes resources and persistent volumes.

Upgrade Tool

A brand-new installer KubeKey is introduced in KubeSphere v3.0.0, with which you can install or upgrade Kubernetes and KubeSphere. For more information, see Upgrade with KubeKey.

KubeKey or ks-installer

ks-installer was the main installation tool as of KubeSphere v2. For users whose Kubernetes clusters were NOT deployed via KubeSphere Installer, they should choose ks-installer to upgrade KubeSphere. For example, if your Kubernetes is hosted by cloud vendors or self provisioned, refer to Upgrade with ks-installer.