Upgrade with KubeKey
KubeKey is recommended for users whose KubeSphere and Kubernetes were both installed by KubeKey. If your Kubernetes cluster was provisioned by yourself or cloud providers, refer to Upgrade with ks-installer.
This tutorial demonstrates how to upgrade your cluster using KubeKey.
Prerequisites
- You need to have a KubeSphere cluster running v3.3.x. If your KubeSphere version is v3.2.x or earlier, upgrade to v3.3.x first.
- Read Release Notes for 3.4.1 carefully.
- Back up any important component beforehand.
- Make your upgrade plan. Two scenarios are provided in this document for all-in-one clusters and multi-node clusters respectively.
Major Updates
In KubeSphere 3.4.1, some changes have made on built-in roles and permissions of custom roles. Therefore, before you upgrade KubeSphere to 3.4.1, please note the following:
Change of built-in roles: Platform-level built-in roles
users-manager
andworkspace-manager
are removed. If an existing user has been bound tousers-manager
orworkspace-manager
, its role will be changed toplatform-regular
after the upgrade is completed. Roleplatform-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 3.4.1, custom roles will be retained, but removed permissions of the custom roles will be revoked.
Download KubeKey
Follow the steps below to download KubeKey before you upgrade your cluster.
Download KubeKey from its GitHub Release Page or use the following command directly.
curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.13 sh -
Run the following command first to make sure you download KubeKey from the correct zone.
export KKZONE=cn
Run the following command to download KubeKey:
curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.13 sh -
Note
export KKZONE=cn
again before you proceed with the steps below.Note
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.
Info
All-in-one cluster
Run the following command to use KubeKey to upgrade your single-node cluster to KubeSphere 3.4 and Kubernetes v1.22.12:
./kk upgrade --with-kubernetes v1.22.12 --with-kubesphere v3.4.1
To upgrade Kubernetes to a specific version, explicitly provide the version after the flag --with-kubernetes
. Available versions are v1.20.x, v1.21.x, v1.22.x, v1.23.x, * v1.24.x, * v1.25.x, and * v1.26.x. 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.
Multi-node cluster
Step 1: Generate a configuration file using KubeKey
This command creates a configuration file sample.yaml
of your cluster.
./kk create config --from-cluster
Note
~/.kube/config
. You can change it with the flag --kubeconfig
.Step 2: Edit the configuration file template
Edit sample.yaml
based on your cluster configuration. Make sure you replace the following fields correctly.
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).
Note
Cluster
section of the complete configuration file for more information.Step 3: Upgrade your cluster
The following command upgrades your cluster to KubeSphere 3.4 and Kubernetes v1.22.12:
./kk upgrade --with-kubernetes v1.22.12 --with-kubesphere v3.4.1 -f sample.yaml
To upgrade Kubernetes to a specific version, explicitly provide the version after the flag --with-kubernetes
. Available versions are v1.20.x, v1.21.x, * v1.22.x, * v1.23.x, and v1.24.x. 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.
Note
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.