This section describes how to perform an offline upgrade from KubeSphere Enterprise v4.1.2 to KubeSphere Enterprise v4.2.0 without Internet access.

Prerequisites

  • Contact the KubeSphere Enterprise support team to get the KubeSphere Enterprise v4.2.0 installation package and license.

  • 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

Preparation

1. Unpack the Installation Package

  1. Transfer the KubeSphere Enterprise installation package to the cluster node to be upgraded and log in to that node.

  2. Run the following command to unpack the v4.2.0 installation package (replace <package name> with the actual package name).

    tar -zxvf <package name>
    Attention

    Ensure that the directory has sufficient available space, preferably greater than 100 GB.

  3. Enter the directory generated after unpacking the installation package.

    cd <directory>

2. Push Images

  1. In the v4.2.0 directory, edit the config-sample.yaml file created during the installation and modify the registry section within it.

        privateRegistry: "dockerhub.kubekey.local/kse" # Replace with the actual image registry address
        auths:
          "dockerhub.kubekey.local":  # Replace with the actual image registry address
              username: admin           # Replace with the username of the image registry
              password: Harbor12345     # Replace with the password of the image registry
              skipTLSVerify: true
              plainHTTP: true   # Set this parameter to true if the image registry uses http

  2. Push the images to the image registry.

    ./kk artifact images push -f config-sample.yaml -a kubekey-artifact.tar.gz

Upgrade KubeSphere Enterprise

KubeSphere Enterprise v4.1 and later versions use the helm chart method to upgrade ks-core.

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.

    		 
    # Use the extension-resources-patch.sh script located in the tools directory of the installation package
bash tools/extension-resources-patch.sh

  3. Check the current cluster’s ks-core configuration.

    helm get value -n kubesphere-system ks-core

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

    If there are other parameters besides the image registry, image version, cloud, and upgrade in the previous step, please add them to the following 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: dockerhub.kubekey.local/kse
extension:
  imageRegistry: dockerhub.kubekey.local/kse

# 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.

    helm upgrade --install ks-core charts/ks-core -n kubesphere-system -f kse-v4.2.0-host-custom-values.yaml --wait --debug
    Attention

    Replace charts/ks-core with the actual path of the ks-core chart in the current environment.

  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: dockerhub.kubekey.local/kse

# 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:

    helm upgrade --install ks-core charts/ks-core -n kubesphere-system -f kse-v4.2.0-member-custom-values.yaml --wait --debug
    Attention

    Replace charts/ks-core with the actual path of the ks-core chart in the current environment.

  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