Upgrade KubeSphere to Community Edition v4.2.0
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
-
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.
-
Create the
collect-node-info.shscript file.vi collect-node-info.shPaste 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" -
Run the script.
Note Before executing the script, you need to install the
jqJSON processor. Please choose the corresponding installation method based on your operating system.bash collect-node-info.sh -
Check the CPU data in the last column.
-
-
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
-
-
Check if the current deployment environment meets the KubeSphere Environment Requirements.
Step 2: Backup Data
-
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 -
Check the running status of KubeSphere components.
ks statusIf 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.
-
Backup the CR (Custom Resource) data for KubeSphere and extensions.
ks backupAttention 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:
-
Migrate ks-core data.
ks migrate ks-coreAfter executing the command, follow the prompt to enter
yand 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.
-
Migrate extension data, using DevOps as an example.
ks migrate devopsAfter executing the command, follow the prompt to enter
yand 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.