Skip to main content

KubeSphere Deployment Guide

Overview​

This guide provides instructions for deploying KubeSphere, an enterprise-grade container platform, on TKE. KubeSphere provides a web-based UI for Kubernetes cluster management, application deployment, and DevOps workflows.

Prerequisites​

Cluster Requirements​

  • Kubernetes cluster version 1.19+
  • Minimum 2 CPU cores and 4GB RAM per node
  • Persistent storage for platform data
  • Load balancer for external access

Resource Requirements​

Minimum Requirements:

  • 8 CPU cores total
  • 16GB RAM total
  • 100GB storage

Recommended for Production:

  • 16+ CPU cores total
  • 32GB+ RAM total
  • 500GB+ storage

Deployment Methods​

Method 1: kubectl Installation​

Install KubeSphere Core Components​

# Install KubeSphere core components
kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.3.0/kubesphere-installer.yaml

# Install KubeSphere configurations
kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.3.0/cluster-configuration.yaml

Verify Installation​

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

Method 2: Helm Installation​

Add KubeSphere Helm Repository​

helm repo add kubesphere https://charts.kubesphere.io/main
helm repo update

Install KubeSphere​

helm install kubesphere kubesphere/ks-installer \
  --namespace kubesphere-system \
  --create-namespace \
  --set global.persistence.storageClass=cbs-ssd \
  --set global.domain=ks.example.com

Configuration​

KubeSphere Configuration​

cluster-configuration.yaml​

apiVersion: installer.kubesphere.io/v1alpha1
kind: ClusterConfiguration
metadata:
  name: ks-installer
  namespace: kubesphere-system
spec:
  persistence:
    storageClass: "cbs-ssd"
  etcd:
    monitoring: true
    endpointIps: "192.168.0.7,192.168.0.8,192.168.0.9"
    port: 2379
    tlsEnable: true
  common:
    mysqlVolumeSize: "20Gi"
    minioVolumeSize: "20Gi"
    etcdVolumeSize: "20Gi"
    openldapVolumeSize: "2Gi"
    redisVolumSize: "2Gi"
  alerting:
    enabled: true
  auditing:
    enabled: true
  devops:
    enabled: true
    jenkinsMemoryLim: "2Gi"
    jenkinsMemoryReq: "1500Mi"
    jenkinsVolumeSize: "8Gi"
  events:
    enabled: true
    ruler:
      enabled: true
      replicas: 2
  logging:
    enabled: true
    logsidecarReplicas: 2
  metrics_server:
    enabled: true
  monitoring:
    prometheusReplicas: 1
    prometheusMemoryRequest: "400Mi"
    prometheusVolumeSize: "20Gi"
  multicluster:
    clusterRole: host
  networkpolicy:
    enabled: true
  notification:
    enabled: true
  openpitrix:
    enabled: true
  servicemesh:
    enabled: true

Ingress Configuration​

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kubesphere-console
  namespace: kubesphere-system
  annotations:
    kubernetes.io/ingress.class: "nginx"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - ks.example.com
    secretName: kubesphere-tls
  rules:
  - host: ks.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: ks-console
            port:
              number: 80

Platform Features​

Application Management​

App Templates​

KubeSphere provides application templates for common workloads:

  • MySQL, Redis, PostgreSQL databases
  • WordPress, Jenkins, GitLab applications
  • Custom application templates

Application Deployment​

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sample-app
  labels:
    app: sample-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: sample-app
  template:
    metadata:
      labels:
        app: sample-app
    spec:
      containers:
      - name: app
        image: nginx:latest
        ports:
        - containerPort: 80

DevOps Pipeline​

Jenkins Integration​

KubeSphere integrates Jenkins for CI/CD pipelines:

  • Visual pipeline editor
  • Multi-branch pipeline support
  • Integration with Git repositories

Pipeline Example​

pipeline {
  agent any
  stages {
    stage('Clone') {
      steps {
        git branch: 'main', url: 'https://github.com/example/app.git'
      }
    }
    stage('Build') {
      steps {
        sh 'docker build -t app:latest .'
      }
    }
    stage('Deploy') {
      steps {
        sh 'kubectl apply -f k8s/deployment.yaml'
      }
    }
  }
}

Monitoring and Logging​

Built-in Monitoring​

KubeSphere provides comprehensive monitoring:

  • Cluster resource monitoring
  • Application performance monitoring
  • Custom metric collection

Log Management​

  • Centralized log collection
  • Log search and analysis
  • Log retention policies

Storage Configuration​

Persistent Volume Claims​

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: kubesphere-mysql-pvc
  namespace: kubesphere-system
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  storageClassName: cbs-ssd

Storage Classes​

Configure storage classes for different workloads:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: cbs-ssd
provisioner: com.tencent.cloud.csi.cbs
parameters:
  type: CLOUD_SSD
reclaimPolicy: Delete
volumeBindingMode: Immediate

Security Features​

Multi-tenancy​

KubeSphere supports multi-tenant environments:

  • Workspace isolation
  • Role-based access control (RBAC)
  • Resource quotas and limits

Network Policies​

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: kubesphere-network-policy
  namespace: kubesphere-system
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          kubesphere.io/namespace: kubesphere-system

Integration with TKE​

TKE Cluster Integration​

KubeSphere can manage TKE clusters:

  • Multi-cluster management
  • Unified application deployment
  • Cross-cluster monitoring

Load Balancer Integration​

Configure TKE load balancers for KubeSphere services:

apiVersion: v1
kind: Service
metadata:
  name: kubesphere-console
  namespace: kubesphere-system
  annotations:
    service.kubernetes.io/qcloud-loadbalancer-internal-subnetid: subnet-xxxxxx
spec:
  type: LoadBalancer
  ports:
  - port: 80
    targetPort: 80
  selector:
    app: ks-console

Troubleshooting​

Common Issues​

Installation Failures​

  • Check resource availability
  • Verify storage class configuration
  • Inspect installer logs

Access Issues​

  • Verify ingress configuration
  • Check DNS resolution
  • Test service connectivity

Performance Issues​

  • Monitor resource utilization
  • Check storage performance
  • Optimize configuration parameters

Debug Commands​

# Check KubeSphere pod status
kubectl get pods -n kubesphere-system

# Check service endpoints
kubectl get endpoints -n kubesphere-system

# Check installation logs
kubectl logs -n kubesphere-system -l app=ks-install

# Check KubeSphere configuration
kubectl get clusterconfiguration -n kubesphere-system

Backup and Recovery​

Platform Backup​

apiVersion: batch/v1
kind: CronJob
metadata:
  name: kubesphere-backup
  namespace: kubesphere-system
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: kubesphere/ks-backup:latest
            command:
            - /bin/bash
            - -c
            - |
              # Backup KubeSphere data
              ks-backup create
            volumeMounts:
            - name: backup-data
              mountPath: /backup
          restartPolicy: OnFailure
          volumes:
          - name: backup-data
            persistentVolumeClaim:
              claimName: kubesphere-backup-pvc