1. Release Notes
    1. Release Notes - 2.1.1Latest
    1. Release Notes - 2.1.0
    1. Release Notes - 2.0.2
    1. Release Notes - 2.0.1
    1. Release Notes - 2.0.0
  1. Introduction
    1. Introduction
    1. Features
    1. Architecture
    1. Advantages
    1. Glossary
  1. Installation
    1. Introduction
      1. Intro
      2. Port Requirements
      3. Kubernetes Cluster Configuration
    1. Install on Linux
      1. All-in-One Installation
      2. Multi-Node Installation
      3. High Availability Configuration
      4. Air Gapped Installation
      5. StorageClass Configuration
      6. Enable All Components
    1. Install on Kubernetes
      1. Prerequisites
      2. Install on K8s
      3. Air Gapped Installation
      4. Install on GKE
    1. Pluggable Components
      1. Pluggable Components
      2. Enable Application Store
      3. Enable DevOps System
      4. Enable Logging System
      5. Enable Service Mesh
      6. Enable Alerting and Notification
      7. Enable Metrics-server for HPA
      8. Verify Components Installation
    1. Upgrade
      1. Overview
      2. All-in-One
      3. Multi-node
    1. Third-Party Tools
      1. Configure Harbor
      2. Access Built-in SonarQube and Jenkins
      3. Enable built-in Grafana Installation
      4. Load Balancer plugin in Bare Metal - Porter
    1. Authentication Integration
      1. Configure LDAP/AD
    1. Cluster Operations
      1. Add or Cordon Nodes
      2. High Risk Operations
      3. Uninstall KubeSphere
  1. Quick Start
    1. 1. Getting Started with Multi-tenancy
    1. 2. Expose your App Using Ingress
    1. 3. Compose and Deploy Wordpress to K8s
    1. 4. Deploy Grafana Using App Template
    1. 5. Job to Compute π to 2000 Places
    1. 6. Create Horizontal Pod Autoscaler
    1. 7. S2I: Publish your App without Dockerfile
    1. 8. B2I: Publish Artifacts to Kubernete
    1. 9. CI/CD based on Spring Boot Project
    1. 10. Jenkinsfile-free Pipeline with Graphical Editing Panel
    1. 11. Canary Release of Bookinfo App
    1. 12. Canary Release based on Ingress-Nginx
    1. 13. Application Store
  1. DevOps
    1. Pipeline
    1. Create SonarQube Token
    1. Credentials
    1. Set CI Node for Dependency Cache
    1. Set Email Server for KubeSphere Pipeline
  1. User Guide
    1. Configration Center
      1. Secrets
      2. ConfigMap
      3. Configure Image Registry
  1. Logging
    1. Log Query
  1. Developer Guide
    1. Introduction to S2I
    1. Custom S2I Template
  1. API Documentation
    1. API Documentation
    1. How to Access KubeSphere API
  1. Troubleshooting
    1. Troubleshooting Guide for Installation
  1. FAQ
    1. Telemetry
KubeSphere®️ 2020 All Rights Reserved.

Troubleshooting Guide for Installation


This guide contains information to help you troubleshoot issues when installing KubeSphere. We summarized the common issues regarding installation on Linux machines or Kubernetes cluster, welcome to contribute your diagnostic conclusions or experience if it is not included in this guide.

Inspect the Installation Logs

  • When you installing KubeSphere or enabling the KubeSphere pluggable components, how to inspect the logs?


You may need to verify if the installation is successful or not. Please inspect the dynamic real-time logs output from the Pod ks-installer. The installation logs is very helpful to debug and locate issues.

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

How to Restart ks-installer

  • When I see the installation process get stucked for long time, how to restart the installation?


You can delete the Pod ks-installer or restart the Deployment it to reinstall.

kubectl rollout restart deploy -n kubesphere-system ks-installer

Create client certificate failed

  • Everything seems OK except the "ks-account" Pod that is in "CrashLoopBackOff" mode. The pod fails with create client certificate failed: <nil>. I can display the console login page but can't login, it fails with"unable to access backend services".
$ kubectl get pods -n kubesphere-system
NAME                                   READY   STATUS             RESTARTS   AGE
ks-account-789cd8bbd5-nlvg9            0/1     CrashLoopBackOff   20         79m
ks-apigateway-5664c4b76f-8vsf4         1/1     Running            0          79m
ks-apiserver-75f468d48b-9dfwb          1/1     Running            0          79m
ks-console-78bddc5bfb-zlzq9            1/1     Running            0          79m
ks-controller-manager-d4788677-6pxhd   1/1     Running            0          79m
ks-installer-75b8d89dff-rl76c          1/1     Running            0          81m
openldap-0                             1/1     Running            0          80m
redis-6fd6c6d6f9-6nfmd                 1/1     Running            0          80m

$ kubectl logs -n kubesphere-system ks-account-789cd8bbd5-nlvg9
W0226 00:40:43.093650       1 client_config.go:549] Neither --kubeconfig nor --master was specified.  Using the inClusterConfig.  This might not work.
E0226 00:40:44.709957       1 kubeconfig.go:62] create client certificate failed: <nil>
E0226 00:40:44.710030       1 im.go:1030] create user kubeconfig failed sonarqube create client certificate failed: <nil>
E0226 00:40:44.710057       1 im.go:197] user init failed sonarqube create client certificate failed: <nil>
E0226 00:40:44.710073       1 im.go:87] create default users user sonarqube init failed: create client certificate failed: <nil>
Error: user sonarqube init failed: create client certificate failed: <nil>


KubeSphere uses CSR to issue kubeconfig to each user, that needs extra configuration on kube-apiserver, refer to Managing tls in a cluster. A standard Kubernetes cluster is enabled by default, but it is not enabled on a RKE. So you need to add this manually:

You can add in the RKE cluster config file the following, see how to activate the CSR signing feature in RKE for further information.

      cluster-signing-cert-file: /etc/kubernetes/ssl/kube-ca.pem
      cluster-signing-key-file: /etc/kubernetes/ssl/kube-ca-key.pem

ks-openldap does not exist

  • How to solve this issue like \"ks-openldap\" does not exist as follows when I installing KubeSphere on the existing Kubernetes cluster?
Error: validation failed: [services \"openldap\" not found, statefulsets.apps \"openldap\" not found]", "stderr_lines": ["Error: validation failed: [services \"openldap\" not found, statefulsets.apps \"openldap\" not found]"], "stdout": "Release \"ks-openldap\" does not exist. Installing it now.


You can try to change the helm version to 2.16.1, or try to delete openldap using helm del --purge ks-openldap, and restart the Pod ks-installer using kubectl rollout restart deploy -n kubesphere-system ks-installer.