This section describes how to upgrade from KubeSphere Open Source Edition v3.x or v4.x to KubeSphere Community Edition v4.2.0.

Prerequisites

  • Ensure the current Kubernetes version is v1.23.x ~ v1.32.x.

  • If extensions have special configurations, back up the extension configurations. In the "Extension Config" dialog, download the file for backup.

  • To avoid data loss, please back up all important data in advance.

Step 1: Pre-upgrade Environment Check

  1. Check the current cluster scale.

    The total cluster scale for KubeSphere Community Edition must not exceed 128 vCPUs. If the cluster exceeds this scale, you can only view resources but cannot create or modify them. Run the following script before upgrading to check the current cluster scale.

    1. Create the collect-node-info.sh script file.

      vi collect-node-info.sh

      Paste the following content and save:

      #!/bin/bash
      t=0
      printf "┌────────────────────┬─────────────────────────┬────────────┐\n│ %-18s │ %-23s │ %-10s │\n├────────────────────┼─────────────────────────┼────────────┤\n" "Cluster" "Node" "CPU(cores)"
      while IFS=$'\t' read -r c k; do
        [[ -n $k ]] && f=$(mktemp) && echo "$k"|base64 -d>"$f" && a="--kubeconfig=$f"
        cc=0
        while read -r n cpu; do
          [[ $cpu == *m ]] && v=$(awk "BEGIN{print ${cpu%m}/1000}") || v=$cpu
          printf "│ %-18s │ %-23s │ %-10s │\n" "$c" "$n" "$v"
          cc=$(awk "BEGIN{print $cc+$v}")
        done < <(kubectl $a get nodes -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.status.capacity.cpu}{"\n"}{end}')
        printf "│ %-18s │ %-23s │ %-10s │\n" "$c" "Cluster Total" "$cc"
        t=$(awk "BEGIN{print $t+$cc}")
        [[ -n $f ]] && rm -f "$f"
      done < <(
        if [[ $(kubectl get clusters -o json 2>/dev/null | jq '.items|length') -eq 0 ]];
          then echo -e "\t"
        else
          kubectl get clusters -o json | jq -r '.items[] | [.metadata.name,.spec.connection.kubeconfig] | @tsv'
        fi
      )
      printf "├────────────────────┼─────────────────────────┼────────────┤\n│ %-18s │ %-23s │ %-10s │\n└────────────────────┴─────────────────────────┴────────────┘\n" "All Clusters" "" "$t"
    2. Run the script.

      Note

      Before executing the script, you need to install the jq JSON processor. Please choose the corresponding installation method based on your operating system.

      bash collect-node-info.sh
    3. Check the CPU data in the last column.

  2. Confirm whether the extensions to be upgraded are included in the Community Edition’s support list.

    KubeSphere Community Edition supports the following extensions. Other extensions are restricted from use in the Community Edition. The specific list is as follows:

    • WizTelemetry Platform Service

    • WizTelemetry Monitoring

    • WizTelemetry Alerting

    • WizTelemetry Notification

    • WizTelemetry Data Pipeline

    • Grafana for WizTelemetry

    • Grafana Loki for WizTelemetry

    • Metrics Server

    • KubeSphere Gateway

    • DevOps

    • Gatekeeper

    • cert-manager

    • NVIDIA GPU Operator

    • DeepSeek

    • Higress

    • ob-operator

    • oceanbase-dashboard

    • Fluid

  3. Check if the current deployment environment meets the KubeSphere Environment Requirements.

Step 2: Backup Data

  1. Install the KubeSphere command-line tool on the cluster node.

    IMAGE=registry.cn-beijing.aliyuncs.com/kse/cli:latest
    POD=kubesphere-cli
    NS=default
    
    kubectl run "$POD" -n "$NS" --image="$IMAGE" -- sleep 120 \
      && kubectl wait --for=condition=Ready pod/"$POD" -n "$NS" --timeout=60s \
      && kubectl cp "$NS/$POD":/usr/local/bin/ks /usr/local/bin/ks \
      && chmod +x /usr/local/bin/ks \
      && ln -sf /usr/local/bin/ks /usr/local/bin/kubectl-ks \
      && kubectl delete pod "$POD" -n "$NS" --wait=false
  2. Check the running status of KubeSphere components.

    ks status

    If the following message is displayed at the end, it indicates that all components are running normally.

    ✅ All components are running normally. Review any warning messages above if applicable.
  3. Backup the CR (Custom Resource) data for KubeSphere and extensions.

    ks backup
    Attention

    This command only backs up CR data. To prevent data loss, please back up all important data before uninstalling.

    If the following message is displayed at the end, it indicates the backup was successful.

    ✅ Backup completed. File saved at: 20250925/backup.tgz

Step 3: Uninstall KubeSphere and Clean Data

Uninstall KubeSphere and extensions and clean up data.

ks uninstall --purge

If the following message is displayed at the end, it indicates the uninstallation and cleanup was successful.

✅ Uninstallation completed successfully.

Step 4: Install KubeSphere Community Edition

Refer to the Installation Guide to install KubeSphere.

Note

The installation commands for KubeSphere Community Edition and KubeSphere Enterprise are the same.

Step 5: Install Extensions

Install extensions in the KubeSphere Web Console. For extensions with special configurations that have been backed up, you can upload the configuration files with one click.

Step 6: Migrate Data

Migrate data for KubeSphere or extensions, restore backup data, and achieve cross-cluster data migration.

Currently, only the following three types of data migration are supported:

  • ks-core: Includes users, RBAC rules, and workspaces.

  • DevOps: Includes credentials, pipelines, and continuous deployments.

  • KubeSphere Gateway (gateway) data.

Migration Steps:

  1. Migrate ks-core data.

    ks migrate ks-core

    After executing the command, follow the prompt to enter y and press Enter. You will see that ks-core related resources have been automatically created. Example output is as follows:

    15:44:29 INFO  Found 2 users to migrate
    15:44:29 INFO  iam.kubesphere.io/v1beta1, Kind=User/admin in cluster unchanged
    15:44:29 INFO  iam.kubesphere.io/v1beta1, Kind=User/cindy in cluster created
    15:44:29 INFO  Found 2 workspacetemplates to migrate
    15:44:29 INFO  tenant.kubesphere.io/v1beta1, Kind=WorkspaceTemplate/system-workspace in cluster unchanged
    15:44:29 INFO  tenant.kubesphere.io/v1beta1, Kind=WorkspaceTemplate/ws1 in cluster created

    Check in the KubeSphere Web Console, and you will find that users, workspaces, etc., have been successfully migrated.

  2. Migrate extension data, using DevOps as an example.

    ks migrate devops

    After executing the command, follow the prompt to enter y and press Enter. You will see that DevOps related resources have been automatically created.

    Check in the KubeSphere Web Console, and you will find that credentials, pipelines, and continuous deployments have been successfully migrated.

At this point, KubeSphere upgrade is complete.