This section explains how to upgrade from KubeSphere Enterprise v4.1.2 or v4.1.3 to v4.2.0 when Internet access is available.

Prerequisites

  • Ensure current KubeSphere Enterprise version is v4.1.2 or v4.1.3.

  • Ensure current Kubernetes version is v1.23.x to v1.32.x.

  • For extensions with special configurations, back up extension configurations by downloading files from the "Extension Config" dialog.

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

Attention

  1. If you customized the nodeShell image in v4.1.x, specify the nodeShell image in the upgrade configuration file kse-v4.2.0-host-custom-values.yaml as shown below:

    Example configuration in v4.1.x:

    nodeShell:
  image:
    registry: ""
    repository: kubesphereio/kubectl
    tag: "v1.27.12"
    pullPolicy: IfNotPresent

    Configure in kse-v4.2.0-host-custom-values.yaml as:

    terminal:
  kubectl:
    enabled: true
    image:
      registry: ""
      repository: kubesphereio/kubectl
      tag: "v1.33.1"
      pullPolicy: IfNotPresent
  node:
    enabled: true
    image:
      registry: ""
      repository: kubesphereio/kubectl
      tag: "v1.33.1"
      pullPolicy: IfNotPresent
  pod:
    enabled: true
    uploadFileLimit: "100Mi"
    uploadFileEnabled: true
    downloadFileEnabled: true

  2. Starting from v4.1.3, cluster role and host cluster name configurations in ks-core chart have changed. When upgrading from v4.1.2, configure as shown below (v4.1.3 unaffected):

    multicluster:
  # Cluster role name
  role: ""
  # Host cluster name (priority: direct specification > reading from kubesphere-config > default name host)
  hostClusterName: ""

  3. Starting from v4.1.3, the following parameter is deprecated. Remove it or set to false in kse-v4.2.0-host-custom-values.yaml:

    upgrade:
  enabled: false

Upgrade KubeSphere Enterprise

KubeSphere Enterprise v4.1 and later versions use Helm charts for ks-core upgrades.

Upgrade Host Cluster

  1. Verify the current cluster is the target host cluster for upgrade:

    kubectl get node -o wide

  2. KubeSphere Enterprise v4.1.3 removed kse-extensions-publish and integrated it into the ks-core chart. For v4.1.2 to v4.2.0 upgrades, you should patch extension resources created by KubeSphere Enterprise previous versions:

    Note

    This step only applies to v4.1.2 → v4.2.0 upgrades. Skip for v4.1.3 → v4.2.0.

    1. Create the extension-resources-patch.sh script to handle conflicts from kse-extension-publish created resources:

      vi extension-resources-patch.sh

      Paste and save:

      #!/bin/bash

# Resolve resource template conflicts
kubectl -n kubesphere-system label deploy extensions-museum app.kubernetes.io/managed-by=Helm
kubectl -n kubesphere-system annotate deploy extensions-museum meta.helm.sh/release-name=ks-core
kubectl -n kubesphere-system annotate deploy extensions-museum meta.helm.sh/release-namespace=kubesphere-system

kubectl -n kubesphere-system label service extensions-museum app.kubernetes.io/managed-by=Helm
kubectl -n kubesphere-system annotate service extensions-museum meta.helm.sh/release-name=ks-core
kubectl -n kubesphere-system annotate service extensions-museum meta.helm.sh/release-namespace=kubesphere-system

kubectl -n kubesphere-system label secret extensions-museum-certs app.kubernetes.io/managed-by=Helm
kubectl -n kubesphere-system annotate secret extensions-museum-certs meta.helm.sh/release-name=ks-core
kubectl -n kubesphere-system annotate secret extensions-museum-certs meta.helm.sh/release-namespace=kubesphere-system

# Resolve repository reference conflicts
for item in $(kubectl get extensionversions.kubesphere.io -o jsonpath="{.items[*].metadata.name}"); do
    kubectl patch extensionversions.kubesphere.io $item --type merge -p '{"spec":{"repository":"extensions-museum"}}'
    kubectl label extensionversions.kubesphere.io $item kubesphere.io/repository-ref=extensions-museum
done
for item in $(kubectl get extensions.kubesphere.io -o jsonpath="{.items[*].metadata.name}"); do
    kubectl label extensions.kubesphere.io $item kubesphere.io/repository-ref=extensions-museum
done

    2. Execute the script:

      bash extension-resources-patch.sh

  3. Check current ks-core configuration:

    helm get values -n kubesphere-system ks-core

  4. Create the upgrade configuration file with the following content:

    If the previous step shows parameters beyond image registry, image version, cloud and upgrade, include them in this configuration file.

    cat <<EOF > kse-v4.2.0-host-custom-values.yaml

# Specify image registry for ks-core and extensions
# Modify according to actual environment
global:
  imageRegistry: registry.cn-beijing.aliyuncs.com
extension:
  imageRegistry: ""

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

# Enable HA for ks-core components (ks-apiserver, ks-controller-manager, ks-console)
# Configure according to cluster status
ha:
  enabled: false

# Enable Redis HA (required for ks-apiserver HA)
# If set to false, single-replica Redis will be deployed in kubesphere-system
redisHA:
  enabled: false
EOF

  5. Run the following command to start the upgrade.

    chart=oci://hub.kubesphere.com.cn/kse/ks-core
version=1.2.1
helm upgrade --install -n kubesphere-system --create-namespace ks-core $chart --version $version -f kse-v4.2.0-host-custom-values.yaml --wait --debug

  6. Verify the host cluster upgrade status.

    Run the following command. The pods should be in Running state as shown below.

    root@xxx:~# kubectl get pod -n kubesphere-system
NAME                                         READY   STATUS      RESTARTS   AGE
extensions-museum-85f846dbbd-6xtst           1/1     Running     0          16h
helm-install-ks-console-embed-tnwmf7-wcfjf   0/1     Completed   0          16h
ks-apiserver-7f875b8654-zvhrd                1/1     Running     0          16h
ks-console-997fc9658-dnrqr                   1/1     Running     0          16h
ks-console-embed-775f757548-9vd2s            1/1     Running     0          16h
ks-controller-manager-5f69675d48-qnxv7       1/1     Running     0          16h

  7. Access the KubeSphere Enterprise v4.2.0 web console using the original IP address, administrator username and password.

  8. Check whether all functions and data in the host cluster are working properly.

Upgrade Member Cluster

The member cluster upgrade process is similar to the host cluster, with special attention to member-specific parameters.

  1. Verify the current member cluster is the target for upgrade:

    kubectl get node -o wide

  2. Check member cluster’s ks-core configuration:

    helm get values -n kubesphere-system ks-core

  3. Get the member cluster’s jwtSecret:

    kubectl -n kubesphere-system get cm kubesphere-config -o yaml | grep -v "apiVersion" | grep jwtSecret

  4. Create the upgrade configuration file with the following content:

    If the previous step shows parameters beyond image registry, image version, cloud and upgrade, include them in this configuration file.

    cat <<EOF > kse-v4.2.0-member-custom-values.yaml

# Specify image registry for ks-core
# Modify according to actual environment
global:
  imageRegistry: registry.cn-beijing.aliyuncs.com

# Replace with member cluster's jwtSecret value
authentication:
  issuer:
    jwtSecret: <REPLACE_ME>

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

  5. Run the upgrade command:

    chart=oci://hub.kubesphere.com.cn/kse/ks-core
version=1.2.1
helm upgrade --install -n kubesphere-system --create-namespace ks-core $chart --version $version -f kse-v4.2.0-member-custom-values.yaml --wait --debug

  6. Verify the member cluster upgrade status.

    Run the following command; the ks-agent pod should be in the running state as shown below.

    root@xxx:~# kubectl get pod -n kubesphere-system
NAME                          READY   STATUS      RESTARTS        AGE
ks-agent-5dc5b57977-4x6mf     2/2     Running     0               59m

  7. If you added custom configurations (e.g., --set a=b) in the above upgrade command, you need to add the custom configurations for the member cluster in the web console.

    Method: On the Cluster Management page, click more on the right side of the member cluster you want to edit, and then select Edit Configuration from the dropdown list. In the pop-up window, enter a: b.

    Note

    If you did not include custom configurations in the upgrade command, you do not need to add cluster configurations in the web console.

Upgrade Extensions

Upgrade the required extensions in the Extensions Center. For extensions with special configurations that have been backed up, modify the configurations before upgrading.

  1. In the Extensions Center, click the extension name to enter its details page.

  2. Click more below the extension icon and select Extension Config.

  3. Clear the Custom Config field, enter the customized configurations, then click OK.

  4. Click more below the extension icon again and select Update.

  5. In the Extension Update dialog box, click Start Update and wait for the upgrade to complete.

At this point, KubeSphere Enterprise has completed all upgrades.

Appendix: Upgradeable Extensions List

Extension KSE v4.1.2 KSE v4.1.3 KSE v4.2.0

alloy

Not included

1.0.0

1.0.0

cert-manager

1.0.0

1.0.0

1.0.0

devops

1.1.1

1.1.2

1.2.1

s2i

Not included

Not included

0.1.0

dmp

2.1.3

2.1.4

2.2.0

edgewize

Not included

Not included

3.1.0

gatekeeper

1.0.1

1.0.3

1.0.3

gateway

1.0.2

1.0.3

1.1.1

grafana

10.4.3

10.4.14

10.4.14

ingress-utils

1.0.0

1.0.0

1.0.1

kubeedge

1.13.1

1.13.1

Removed (migrated to EdgeWize)

kubefed

1.0.0

1.0.0

1.1.0

loki

1.0.2

1.0.2

1.0.2

metrics-server

0.7.0

0.7.0

0.7.2

network

1.1.0

1.1.0

1.2.1

nvidia-gpu-operator

23.9.2

23.9.2

23.9.2

oauth2-proxy

7.6.2

7.6.2

7.6.2

openpitrix

2.0.1

2.0.2

2.1.0

opensearch

2.11.1

2.11.1

2.11.1

s2ibuilder

Not included

Not included

0.1.0

servicemesh

1.0.0

1.0.1

1.0.2

springcloud

1.0.1

1.0.1

1.0.2

storage-utils

1.0.0

1.0.0

1.0.1

tempo

Not included

Not included

1.0.0

tower

1.0.0

1.0.0

1.1.0

vector

1.0.4

1.0.4

1.0.4

whizard-alerting

1.0.3

1.0.4

1.0.5

whizard-auditing

1.2.0

1.2.1

1.2.1

whizard-events

1.2.0

1.2.1

1.2.2

whizard-logging

1.2.2

1.2.3

1.2.3

whizard-monitoring-pro

Not included

Not included

1.0.0

whizard-monitoring

1.1.0

1.1.0

1.2.0

whizard-notification

2.5.9

2.6.0

2.6.1

whizard-telemetry-ruler

1.2.0

1.2.0

1.2.0

whizard-telemetry

1.2.2

1.3.0

2.0.0

wiztelemetry-bpfconductor

Not included

Not included

1.0.3

wiztelemetry-tracing

Not included

Not included

1.0.3