Last updated:

Configure KubeSphere High Availability

This section describes how to configure high availability (HA) for KubeSphere.

Attention
KubeSphere high availability depends on Kubernetes high availability of control plane nodes. Ensure Kubernetes is deployed in high availability mode first.

Attention

KubeSphere high availability depends on Kubernetes high availability of control plane nodes. Ensure Kubernetes is deployed in high availability mode first.

1. High Availability Architecture Overview

KubeSphere supports high availability deployment through ha.enabled configuration.

In HA mode, Redis supports two deployment modes:

Redis standalone mode
Redis high availability mode (Redis HA)

2. Version Compatibility

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

3. KubeSphere HA Configuration

3.1 Enabling HA Mode

Create a values.yaml file with the following configuration:

ha:
  enabled: true

4. Redis Configuration

Choose either Redis standalone mode or Redis HA mode and add corresponding configurations to values.yaml.

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

Recommended for production environments, providing 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

Add -f values.yaml when installing or upgrading KubeSphere.

Attention

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

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

# Installation
helm upgrade --install -n kubesphere-system --create-namespace ks-core https://charts.kubesphere.io/main/ks-core-1.1.4.tgz -f values.yaml --debug --wait

# Upgrade
helm upgrade -n kubesphere-system ks-core https://charts.kubesphere.io/main/ks-core-1.1.4.tgz -f values.yaml --debug --wait

6. Configuration Reference

6.1 Redis Standalone Mode

Suitable for small clusters
Uses single Redis instance
Supports basic failover
Simple configuration with low resource consumption

6.2 Redis HA Mode

Recommended for production
Uses Redis cluster
Provides full high availability
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.

Generate an RSA private key.

openssl genrsa -out private_key.pem 2048

View the Base64-encoded key.
```
cat private_key.pem | base64 -w 0
```

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>

Restart KubeSphere components.

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

Verify configuration. Access http://<ks-console-address>/oauth/keys multiple times in browser to check if responses from all replicas are consistent.

Feedback

Was this page Helpful?

Receive the latest news, articles and updates from KubeSphere

Thanks for the feedback. If you have a specific question about how to use KubeSphere, ask it on Slack. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.

Previous : Air-gapped Installation Next : Appendix: Advanced Configuration of KubeSphere Core

What’s on this Page