Last updated:

Upgrade from v4.1.x to v4.1.3

This section explains how to upgrade KubeSphere from v4.1.x to v4.1.3 while maintaining your current Kubernetes version.

Prerequisites

Ensure your current KubeSphere version is v4.1.x.
Ensure your current Kubernetes version is v1.21.x ~ v1.30.x.
If extensions have custom configurations, back them up by downloading configuration files from the "Extension Config" dialog.
Back up all critical data to prevent data loss.

Upgrade KubeSphere

KubeSphere v4.1+ uses Helm for upgrading ks-core.

Upgrade Host Cluster

Verify the target cluster:
kubectl get node -o wide

Export current ks-core configuration:

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

Modify configuration file:

# Pay special attention to these fields while preserving others
global:
  imageRegistry: docker.io
extension:
  imageRegistry: docker.io

# Note: Cluster role parameter changed from 'role' to 'multicluster.role'
multicluster:
  role: host

Run upgrade command:

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

Verify successful upgrade:

helm -n kubesphere-system get metadata ks-core
NAME: ks-core
CHART: ks-core
VERSION: 1.1.4
APP_VERSION: v4.1.3
NAMESPACE: kubesphere-system
REVISION: 26
STATUS: deployed
DEPLOYED_AT: 2025-03-27T11:10:00+08:00

Upgrade Member Cluster

The process is similar to host cluster upgrade but requires attention to member-specific parameters.

Verify target member cluster:
kubectl get node -o wide

Export ks-core configuration:

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

Modify configuration file:

# Pay special attention to these fields
global:
  imageRegistry: docker.io
authentication:
  issuer:
    jwtSecret: <REDACTED>

# Cluster role parameter changed from role to multicluster.role
multicluster:
  role: member

Run upgrade command:

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

Verify successful upgrade:

helm -n kubesphere-system get metadata ks-core
NAME: ks-core
CHART: ks-core
VERSION: 1.1.4
APP_VERSION: v4.1.3
NAMESPACE: kubesphere-system
REVISION: 13
STATUS: deployed
DEPLOYED_AT: 2025-03-27T11:10:00+08:00

Upgrade Extensions

Upgrade required extensions in Extensions Center.

Navigate to extension details page in Extensions Center.
Click below the extension icon and select Extension Config.
In the dialog, click Restore Recommended Configuration, then manually modify with custom settings before confirming.
Click again and select Update.
In the update dialog, click Start Update and wait for completion.

KubeSphere upgrade is now complete.

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 : Appendix: Advanced Configuration of KubeSphere Core Next : Upgrade from v3.4.x to v4.1.3

What’s on this Page