DEV Community: kubesphere.io

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

kubesphere.io — Fri, 13 Jun 2025 08:14:02 +0000

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!

Quick Deployment of High Availability Kubernetes 1.33.0 Cluster Based on KubeKey 3.1.9

kubesphere.io — Fri, 30 May 2025 10:43:02 +0000

Author: Ding Xinlei, Cloud-Native Operations Engineer
Focused on deep integration of KubeSphere and Kubernetes (K8s), passionate about simplifying Kubernetes operations and enabling enterprise cloud-native transformation.

🌍 Compatibility Notice

This guide is optimized for global users.
Default deployment uses public registries (docker.io, quay.io, ghcr.io).
Harbor (private registry) is optional, only needed for offline / air-gapped environments.
Timezone is set to UTC.
NTP server is pool.ntp.org.

Background
Software Versions
Server Planning
Host Initialization
Package Preparation
Optional: Harbor Setup (Offline)
Kubernetes Cluster Installation
KubeSphere Installation
Conclusion

1. Background

1.1 KubeKey 3.1.9 Updates

Support for Kubernetes 1.33.0
Bug fixes:
- kubelet cgroup configuration
- UFW and IPVS issues

1.2 Kubernetes 1.33.0 Highlights

In-place vertical scaling
Sidecar GA
Indexed Jobs GA
Improved ServiceAccount token security
kubectl subresource support
Dynamic Service CIDR expansion
Enhanced User Namespaces
OCI image mounting
Ordered namespace deletion

2. Software Versions

Component	Version
OS	openEuler 22.03 (LTS-SP3) amd64
Docker	24.0.9
Kubernetes	v1.33.0
KubeSphere	v4.1.3
KubeKey	v3.1.9

3. Server Planning

IP Address	Hostname	Role
192.168.118.180	k8s-master1	master
192.168.118.181	k8s-node01	worker
192.168.118.182	k8s-node02	worker

4. Host Initialization

4.1 Configure Static IP

vim /etc/sysconfig/network-scripts/ifcfg-ens33
TYPE=Ethernet
PROXY_METHOD=none
BROWSER_ONLY=no
BOOTPROTO=static
IPADDR=192.168.118.180
NETMASK=255.255.255.0
GATEWAY=192.168.118.2
DNS1=192.168.118.2
DEFROUTE=yes
IPV4_FAILURE_FATAL=no
IPV6INIT=yes
IPV6_AUTOCONF=yes
IPV6_DEFROUTE=yes
IPV6_FAILURE_FATAL=no
IPV6_ADDR_GEN_MODE=stable-privacy
NAME=ens33
DEVICE=ens33
ONBOOT=yes

4.2 Disable SELinux

sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
setenforce 0

4.3 Set Hostname


hostnamectl set-hostname <hostname>

4.4 Disable Swap for Performance Improvement

swapoff -a
vim /etc/fstab

4.5 Disable Firewalld

systemctl stop firewalld
systemctl disable firewalld

4.6 Install Basic Packages

yum install curl socat conntrack ebtables ipset ipvsadm -y

4.7 Create Data Directories

timezone: "UTC"
ntpServers:
  - pool.ntp.org

5. Package Preparation

5.1 Download KubeKey

curl -sSL https://get-kk.kubesphere.io | sh -

5.2 Prepare `manifest.yaml`

./kk create manifest --with-kubernetes v1.33.0 --with-registry
vim manifest-sample.yaml

Example image sources (use public registries):

images:
  - docker.io/library/pause:3.9
  - k8s.gcr.io/kube-apiserver:v1.33.0
  - k8s.gcr.io/kube-controller-manager:v1.33.0
  - k8s.gcr.io/kube-scheduler:v1.33.0
  - docker.io/coredns/coredns:1.9.3
  ...

5.3 Optional: Export Images (Offline Only)

./kk artifact export -m manifest-sample.yaml -o kubesphere.tar.gz

6. Optional: Harbor Setup (Offline)

Note: Harbor is required only for offline or air-gapped environments.
Online users can skip this section.

6.1 Create Harbor Config (Optional)

./kk create config --with-kubernetes v1.33.0 -f config-sample.yaml

Example:

registry:
  type: "harbor"
  privateRegistry: "your.harbor.domain"

6.2 Push Images (Optional)

./kk artifact image push -f config-sample.yaml -a kubesphere.tar.gz

7. Kubernetes Cluster Installation

7.1 Create Cluster

./kk create cluster -f config-sample.yaml --with-local-storage

7.2 Verify Cluster

kubectl get nodes

8. KubeSphere Installation

8.1 Install KubeSphere via Helm

helm upgrade --install -n kubesphere-system --create-namespace ks-core ks-core-1.1.5.tgz \
  --set global.imageRegistry=docker.io/ks \
  --set extension.imageRegistry=docker.io/ks \
  --set ksExtensionRepository.image.tag=v1.1.6 \
  --debug \
  --wait

8.2 Verify Deployment

kubectl get pods -n kubesphere-system

Access KubeSphere:

http://<master-ip>:30880

Default credentials:

Username: admin
Password: P@88w0rd

9. Conclusion

You have successfully deployed a high-availability Kubernetes 1.33.0 cluster with KubeKey 3.1.9 and KubeSphere 4.1.3.

✅ For online deployments, public registries (docker.io, etc.) are used by default.
✅ For offline deployments, Harbor is supported (optional).

You can now customize your cluster with advanced storage, networking, and observability as needed.

Enjoy your cloud-native journey! 🚀

Upgrade Gateway to v1.0.4

kubesphere.io — Mon, 07 Apr 2025 06:06:34 +0000

Instructions

Important Notes

If custom parameters were set during installation, make sure to back up and reset them during the upgrade:

helm get values -n kubesphere-system ks-core | grep -v 'USER-SUPPLIED VALUES' > bak-values.yaml

Step 1: Update the Extension Component Repository

# Without custom parameters
helm upgrade --install -n kubesphere-system --create-namespace ks-core https://charts.kubesphere.io/main/ks-core-1.1.4.tgz --debug --wait --set ksExtensionRepository.image.tag=v1.1.4

# With custom parameters
helm upgrade --install -n kubesphere-system --create-namespace ks-core https://charts.kubesphere.io/main/ks-core-1.1.4.tgz --debug --wait -f bak-values.yaml --set ksExtensionRepository.image.tag=v1.1.4

Step 2: Trigger the Extension Component Repository Update

kubectl patch repository extensions-museum --type=json -p='[{"op": "replace", "path": "/status", "value": {}}]'

Update Gateway version to v1.0.4

Update the extension component configuration

Paste the configuration from the Overview -> Upgrade section into the extension component configuration update box

Step 3: Upgrade Gateway to Version v1.0.4

After the upgrade, update the Gateway extension component configuration according to the "Upgrade" section on the extension component page.

Restart Gateway API Server

kubectl rollout restart deploy -n extension-gateway gateway-agent-backend-apiserver

Update Existing Gateway

If the Gateway is already enabled in the cluster, the update will cause service interruptions. Please schedule an update window in advance.

1. Backup Gateway Configuration

Go to the Gateway details page, click Edit, and record the current custom configuration.

2. Record the nodePort (If Port Consistency is Needed)

In Application Load > Services, locate the Gateway service under kubesphere-controls-system, and record the nodePort port.

3. Disable the Gateway

Click Disable on the Gateway details page.

Note: This step will cause service interruptions.

4. Re-enable the Gateway

If custom configurations exist, please reset them to ensure that the nodePort remains consistent (use the "Edit YAML" option to configure if necessary).

Check Nginx Ingress Version

Make sure the version is:

kubesphere-nginx-ingress-4.12.1

KubeSphere v4.1.3 Open Source Edition Released

kubesphere.io — Fri, 28 Mar 2025 03:47:58 +0000

KubeSphere 4.1.3 Open Source Edition is officially released, featuring multiple functionality optimizations and bug fixes to further enhance security and usability.

Feature Optimizations

Optimized the cascading delete logic for enterprise spaces The cascading delete strategy for enterprise spaces has been changed from passive to active to avoid accidental operations.
Adjusted authorization rules for platform roles and enterprise space roles Further refined RBAC (Role-Based Access Control) authorization rules to improve security.
Optimized data display on the Pod list page Resource status information is displayed more intuitively, improving usability.
Allow users to associate multiple identity providers Users can now bind multiple identity providers (IdP) at the same time, improving flexibility and compatibility.
Support for manually triggering application repository updates Users can now manually refresh the application repository to ensure the latest application version information is retrieved.
New “Access Denied” page Invalid page requests are redirected to an "Access Denied" page.

Bug Fixes

Fixed an issue where application instances could not be upgraded.
Fixed compatibility issues with pre-release Kubernetes versions.
Fixed configuration issues with LDAP identity providers.
Fixed issues where images could not be searched from Docker Hub and Harbor.
Fixed issues with handling special characters in application versions.
Fixed issues preventing the creation of Ingress when the gateway extension is not installed.

Installation and Upgrade

We welcome all users to download and experience this release, and provide valuable feedback.

Important Notes

For more update details, please refer to the
KubeSphere 4.1.3 Release .

For installation and upgrade instructions, refer to the Installation Guide.

Note: Direct upgrades from v3.x to v4.x are not yet supported but are planned to be available in the version update later in April.

Feedback Channels:

Submit Issues: GitHub Issues

Future Outlook

In future version updates, the KubeSphere team will continue to focus on the needs and feedback from the open-source community. We are committed to staying true to our original vision and providing a more stable, secure, and efficient product experience for open-source users. As KubeSphere evolves, we will continue to optimize the platform’s performance and features, especially in terms of usability, security, and multi-cloud environment support, ensuring that users stay ahead in the rapidly changing technological landscape.

We are grateful for the support and contributions of every KubeSphere user, and we will keep working hard to bring you more surprises and useful features. We look forward to growing and progressing with you in future versions.

KubeSphere #Kubernetes #CloudNative #OpenSource #DevOps

DEV Community: kubesphere.io

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

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

Prerequisites Before the Upgrade

Step 1: Upgrade the Host Cluster

Step 2: Upgrade Member Clusters

Step 3: Upgrade Extensions

Final Thoughts & Tips

Quick Deployment of High Availability Kubernetes 1.33.0 Cluster Based on KubeKey 3.1.9

🌍 Compatibility Notice

Table of Contents

1. Background

1.1 KubeKey 3.1.9 Updates

1.2 Kubernetes 1.33.0 Highlights

2. Software Versions

3. Server Planning

4. Host Initialization

4.1 Configure Static IP

4.2 Disable SELinux

4.3 Set Hostname

4.4 Disable Swap for Performance Improvement

4.5 Disable Firewalld

4.6 Install Basic Packages

4.7 Create Data Directories

5. Package Preparation

5.1 Download KubeKey

5.2 Prepare manifest.yaml

5.3 Optional: Export Images (Offline Only)

6. Optional: Harbor Setup (Offline)

6.1 Create Harbor Config (Optional)

6.2 Push Images (Optional)

7. Kubernetes Cluster Installation

7.1 Create Cluster

7.2 Verify Cluster

8. KubeSphere Installation

8.1 Install KubeSphere via Helm

8.2 Verify Deployment

9. Conclusion

Upgrade Gateway to v1.0.4

Instructions

Important Notes

Step 1: Update the Extension Component Repository

Step 2: Trigger the Extension Component Repository Update

Step 3: Upgrade Gateway to Version v1.0.4

Restart Gateway API Server

Update Existing Gateway

1. Backup Gateway Configuration

2. Record the nodePort (If Port Consistency is Needed)

3. Disable the Gateway

4. Re-enable the Gateway

Check Nginx Ingress Version

KubeSphere v4.1.3 Open Source Edition Released

Feature Optimizations

Bug Fixes

Installation and Upgrade

Important Notes

Feedback Channels:

Future Outlook

KubeSphere #Kubernetes #CloudNative #OpenSource #DevOps

5.2 Prepare `manifest.yaml`