How to Seamlessly Upgrade KubeSphere from v4.1.x to v4.1.3

Upgrading your KubeSphere platform is essential to benefit from the latest enhancements and fixes. Here's a comprehensive step-by-step guide to safely upgrade from v4.1.x to v4.1.3 while preserving your current Kubernetes version (v1.21.x–v1.30.x).

Prerequisites Before the Upgrade

1.Confirm your current KubeSphere version is v4.1.x.

2.Kubernetes cluster must be within v1.21.x to v1.30.x.

3.Backup custom configurations of any installed extensions via Extension Config.

4.Take full backups of critical data to avoid loss.

Step 1: Upgrade the Host Cluster

KubeSphere now utilizes Helm for ks-coreupgrades.

a. Verify the target cluster

kubectl get node -o wide

b. Export current values

helm get values -n kubesphere-system ks-core -o yaml > host-cluster-custom-values.yaml

c. Edit values file

Update key sections, for example:

global:
  imageRegistry: docker.io
extension:
  imageRegistry: docker.io

multicluster:
  role: host

d. Execute the upgrade

helm -n kubesphere-system upgrade ks-core \
  https://charts.kubesphere.io/main/ks-core-1.1.4.tgz \
  -f host-cluster-custom-values.yaml \
  --wait --debug

e. Verify success

helm -n kubesphere-system get metadata ks-core

Ensure output shows APP_VERSION: v4.1.3 and a healthy STATUS: deployed

Step 2: Upgrade Member Clusters

For multi-cluster setups, the member clusters follow a similar workflow.

a. Check the cluster

kubectl get node -o wide

b. Export member-specific config

helm get values -n kubesphere-system ks-core -o yaml > member-cluster-custom-values.yaml

c. Edit values file

Adjust the role and JWT secret:

global:
  imageRegistry: docker.io
authentication:
  issuer:
    jwtSecret: <REDACTED>

multicluster:
  role: member

d. Apply the upgrade

helm -n kubesphere-system upgrade ks-core \
  https://charts.kubesphere.io/main/ks-core-1.1.4.tgz \
  -f member-cluster-custom-values.yaml \
  --wait --debug

e. Validate deployment

Run the same helm get metadata check and confirm deployment status.

Step 3: Upgrade Extensions

After ks-core is updated, upgrade your extensions via the console:

1.Open Extensions Center, navigate to your extension details.

2.Click More → Extension Config, restore recommended defaults, then reapply your custom settings.

3.Click More → Update, then Start Update and wait for it to complete

Final Thoughts & Tips

• Always backup your configuration and data before upgrading.

• Track your KubeSphere core chart version: ks-core-1.1.4.tgz corresponds to v4.1.3.

• Use --wait --debug to monitor the Helm upgrade process.

• Validating via helm get metadata ensures deployment health and version integrity.

With these steps, your KubeSphere platform should be running the latest v4.1.3, taking full advantage of platform enhancements and bug fixes. Let us know if you run into any issues or need help—our community and Slack are just a ping away!