Upgrade - Overview

• Before you upgrade your cluster to KubeSphere 3.4, you need to have a KubeSphere cluster running v3.2.x.
• You can choose to only upgrade KubeSphere to 3.4 or upgrade Kubernetes (to a higher version) and KubeSphere (to 3.4) at the same time.
• For Kubernetes versions with an asterisk, some features of edge nodes may be unavailable due to incompatability. Therefore, if you want to use edge nodes, you are advised to install Kubernetes v1.23.x.

** before the upgrade: 

• Implement a simulation in testing environment first. After upgrade successfully in testing environment, then upgrade your cluster in your production environment.
• Recommend to backup( can use Velero to backup & migrate kubernetes resources).    **

There are 2 ways to upgrade Kubernetes.

1. Upgrade with KubeKey

• KubeKey is recommended for users whose KubeSphere and Kubernetes were both installed by KubeKey

+ Requirements

• your kubesphere cluster running v3.3.x. If it isnt, upgrade it.
• back up is important

+ Before upgrade, please note

• Change of built-in roles: Platform-level built-in roles users-manager and workspace-manager are removed. If an existing user has been bound to users-manager or workspace-manager, its role will be changed to platform-regular after the upgrade is completed. Role platform-self-provisioner is added. For more information about built-in roles, refer to Create a user.

• Some permission of custom roles are removed:

  • Removed permissions of platform-level custom roles: user management, role management, and workspace management.
  • Removed permissions of workspace-level custom roles: user management, role management, and user group management.
  • Removed permissions of namespace-level custom roles: user management and role management.
  • After you upgrade KubeSphere to new version, custom roles will be retained, but removed permissions of the custom roles will be revoked.

+ Download Kubekey( command line or github https://github.com/kubesphere/kubekey/releases )

• cmd: curl -sfL https://get-kk.kubesphere.io | VERSION=version sh -
  
  • Make kk executable: chmod +x kk

+ Upgrade KubeSphere and Kubernetes 

Upgrading steps are different for single-node clusters (all-in-one) and multi-node clusters.

• • All-in-one cluster: upgrade single-node cluster to kubeShpere and Kubernetes

             cmd: ./kk upgrade --with-kubernetes version --with-kubesphere version

• • Multi-node cluster:
    
    • Step1 : Generate a configuration file using KubeKey (cmd below use for creating a configuration file sample.yaml of your cluster.)
      • cmd: ./kk create config --from-cluster
    • Step2 : Edit the configuration file template ( Edit sample.yaml based on your cluster configuration )
      • hosts: The basic information of your hosts (hostname and IP address) and how to connect to them using SSH.
      • roleGroups.etcd: Your etcd nodes.
      • controlPlaneEndpoint: Your load balancer address (optional).
      • registry: Your image registry information (optional).
    • Step3 : Upgrade the cluster
      • cmd: ./kk upgrade --with-kubernetes version --with-kubesphere version -f sample.yaml
        

2. Upgrade with ks-installer

• ks-installer is recommended for users whose Kubernetes clusters were not set up by KubeKey, but hosted by cloud vendors or created by themselves.

+ Requirements

• your kubesphere cluster running v3.3.x. If it isnt, upgrade it.
• back up is important

+ Before upgrade, please note

• Change of built-in roles: Platform-level built-in roles users-manager and workspace-manager are removed. If an existing user has been bound to users-manager or workspace-manager, its role will be changed to platform-regular after the upgrade is completed. Role platform-self-provisioner is added. For more information about built-in roles, refer to Create a user.

• Some permission of custom roles are removed:

  • Removed permissions of platform-level custom roles: user management, role management, and workspace management.
  • Removed permissions of workspace-level custom roles: user management, role management, and user group management.
  • Removed permissions of namespace-level custom roles: user management and role management.
  • After you upgrade KubeSphere to new version, custom roles will be retained, but removed permissions of the custom roles will be revoked.

+ Apply ks-installer: cmd to upgrade the cluster

• cmd: kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/kubesphere-installer.yaml  --force