This section explains how to configure high availability for KubeSphere.

Note

KubeSphere high availability relies on high availability of Kubernetes control plane nodes, so ensure Kubernetes is deployed in HA mode first.

1. High Availability Architecture Overview

KubeSphere supports high availability deployment, which can be enabled via ha.enabled.

In HA mode, Redis supports two deployment approaches:

  1. Redis standalone mode

  2. Redis high availability mode (Redis HA)

2. Version Compatibility

KubeSphere HA configuration applies to KubeSphere Enterprise v4.1.2 and later versions.

3. KubeSphere HA Configuration

3.1 Enable HA Mode

Create a values.yaml file with the following configuration:

ha:
  enabled: true

4. Redis Configuration

Choose either Redis standalone or Redis HA mode based on requirements, then add the corresponding configuration to the values.yaml file.

4.1 Redis Standalone Mode

Suitable for small clusters with simple configuration and lower resource consumption.

redis:
  port: 6379
  replicaCount: 1
  image:
    repository: kubesphereio/redis
    tag: 7.2.4-alpine
    pullPolicy: IfNotPresent
  persistentVolume:
    enabled: true
    size: 2Gi

4.2 Redis HA Mode

Designed for production environments with full high availability.

redisHA:
  enabled: true
  redis:
    port: 6379
  image:
    repository: kubesphereio/redis
    tag: 7.2.4-alpine
    pullPolicy: IfNotPresent
  persistentVolume:
    enabled: true
    size: 2Gi

4.3 Redis HA Advanced Configuration

redisHA:
  enabled: true
  # Redis node configuration
  redis:
    port: 6379
  # Persistence configuration
  persistentVolume:
    enabled: true
    size: 2Gi
  # Node affinity
  tolerations:
    - key: node-role.kubernetes.io/master
      effect: NoSchedule
    - key: node-role.kubernetes.io/control-plane
      effect: NoSchedule
    - key: CriticalAddonsOnly
      operator: Exists
  # HA configuration
  hardAntiAffinity: false
  additionalAffinities:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          preference:
            matchExpressions:
              - key: node-role.kubernetes.io/control-plane
                operator: In
                values:
                  - ""
  # HAProxy configuration
  haproxy:
    servicePort: 6379
    containerPort: 6379
    image:
      repository: kubesphereio/haproxy
      tag: 2.9.6-alpine
      pullPolicy: IfNotPresent

5. HA Deployment

When installing or upgrading KubeSphere Enterprise, append -f values.yaml to your command.

Note

The following commands are examples only. Always append -f values.yaml to your actual installation/upgrade command.

 
# Installation
helm install -n kubesphere-system --create-namespace ks-core oci://hub.kubesphere.com.cn/kse/ks-core --version 1.1.0 -f values.yaml

# Upgrade
helm upgrade -n kubesphere-system ks-core oci://hub.kubesphere.com.cn/kse/ks-core --version 1.1.0 -f values.yaml

6. Configuration Notes

6.1 Redis Standalone Mode

  • Designed for small clusters

  • Uses single Redis instance

  • Supports basic failover

  • Simple configuration with low resource overhead

6.2 Redis HA Mode

  • Recommended for production

  • Uses Redis cluster

  • Provides full HA capabilities

  • Supports automatic failover

  • Data persistence

  • Load balancing

7. Optional Configurations

JWT Signing Key Configuration

In high availability environments, configure a custom SignKey to ensure all replicas use the same JWT signing key.

  1. Generate an RSA private key:

    openssl genrsa -out private_key.pem 2048

  2. View the Base64-encoded key content:

    cat private_key.pem | base64 -w 0

  3. Edit KubeSphere configuration:

    kubectl -n kubesphere-system edit cm kubesphere-config

    Add or replace the following field under authentication.issuer:

    signKeyData: <Base64-encoded-private-key>

  4. Restart KubeSphere components:

    kubectl -n kubesphere-system rollout restart deploy ks-apiserver ks-controller-manager

  5. Verify configuration: Access http://<ks-console-address>/oauth/keys multiple times in your browser and verify the data consistency across all replicas.