How to Install KubeSphere 2.1.1 on a Kubernetes Cluster: Step‑by‑Step Guide

What Is KubeSphere?

KubeSphere is a multi‑tenant, application‑centric container platform built on Kubernetes, offering a full‑stack IT automation and DevOps experience with a wizard‑style UI, modular components, and support for both online and offline installations.

Prerequisites

Kubernetes version 1.15.x ≤ v ≤ 1.17.x Helm 2.10.0 ≤ v < 3.0.0 (Helm 2.16.0 not supported) with Tiller installed Cluster must have a default StorageClass Cluster must have internet access unless performing an air‑gapped installation (see KubeSphere offline install guide)

Install Helm and Tiller

If Helm and Tiller are already present, skip this section.

Download Helm v2.16.3:

curl -LO https://github.com/helm/helm/releases/download/v2.16.3/helm-v2.16.3-linux-amd64.tar.gz

Extract and move binaries to /usr/local/bin/.

cp helm /usr/local/bin/</code><code>cp tiller /usr/local/bin/

Verify installation: helm help Create a ServiceAccount for Tiller:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: tiller
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tiller
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: tiller
  namespace: kube-system

Apply the RBAC file: kubectl apply -f helm_rbac.yaml Initialize Helm with a domestic image registry:

helm init --service-account=tiller --tiller-image=registry.cn-hangzhou.aliyuncs.com/google_containers/tiller:v2.16.3 --history-max 300

Check Tiller status; if ImagePullBackOff, manually pull the image.

Confirm Tiller pod is running:

kubectl -n kube-system get pods | grep tiller

Install Persistent Storage and StorageClass (OpenEBS)

Skip if the cluster already has a StorageClass. OpenEBS LocalPV is recommended only for development/testing; use Ceph/GlusterFS for production. Ensure master nodes have no taints before installing KubeSphere.

Check for master taints: kubectl describe node master | grep Taint Remove the master taint if present:

kubectl taint nodes master node-role.kubernetes.io/master:NoSchedule-

Create the openebs namespace: kubectl create ns openebs Install OpenEBS via Helm:

helm init</code><code>helm install --namespace openebs --name openebs stable/openebs --version 1.5.0

List the automatically created StorageClasses: kubectl get sc Set openebs-hostpath as the default StorageClass:

kubectl patch storageclass openebs-hostpath -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Install KubeSphere via kubectl

When the cluster meets the prerequisites, KubeSphere can be installed with a single kubectl apply command.

Minimal Installation

For clusters with >1 CPU core and >2 GiB memory:

kubectl apply -f https://raw.githubusercontent.com/kubesphere/ks-installer/master/kubesphere-minimal.yaml

Full Installation

For clusters with >8 CPU cores and >16 GiB memory (ensure at least one node has >8 GiB free memory):

kubectl apply -f https://raw.githubusercontent.com/kubesphere/ks-installer/master/kubesphere-complete-setup.yaml

If the server cannot access GitHub, download the YAML files from https://github.com/kubesphere/ks-installer/ and apply them locally.

Verification and Access

Monitor the installation logs until completion:

kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l app=ks-install -o jsonpath='{.items[0].metadata.name}') -f

Check that all KubeSphere pods are Running across namespaces: kubectl get pod --all-namespaces Then access the UI at IP:30880 using the default admin credentials admin/P@88w0rd.

Enabling Optional Pluggable Components

If you performed a minimal install, refer to the KubeSphere pluggable components overview (

https://kubesphere.com.cn/docs/zh-CN/installation/pluggable-components/

) and ensure the cluster meets the resource requirements before enabling additional features.