Air-Gapped 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. This tutorial is for upgrading KubeSphere only. Cluster operators are responsible for upgrading Kubernetes beforehand.
Prerequisites
- You need to have a KubeSphere cluster running v3.2.x. If your KubeSphere version is v3.1.x or earlier, upgrade to v3.2.x first.
- Read Release Notes for 3.4.1 carefully.
- Back up any important component beforehand.
- A Docker registry. You need to have a Harbor or other Docker registries. For more information, see Prepare a Private Image Registry.
- Supported Kubernetes versions of KubeSphere 3.4: 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.
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.
Step 1: Prepare Installation Images
As you install KubeSphere in an air-gapped environment, you need to prepare an image package containing all the necessary images in advance.
Download the image list file
images-list.txt
from a machine that has access to Internet through the following command:curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/images-list.txt
Note
This file lists images under##+modulename
based on different modules. You can add your own images to this file following the same rule. To view the complete file, see Appendix.Download
offline-installation-tool.sh
.curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/offline-installation-tool.sh
Make the
.sh
file executable.chmod +x offline-installation-tool.sh
You can execute the command
./offline-installation-tool.sh -h
to see how to use the script:root@master:/home/ubuntu# ./offline-installation-tool.sh -h Usage: ./offline-installation-tool.sh [-l IMAGES-LIST] [-d IMAGES-DIR] [-r PRIVATE-REGISTRY] [-v KUBERNETES-VERSION ] Description: -b : save kubernetes' binaries. -d IMAGES-DIR : the dir of files (tar.gz) which generated by `docker save`. default: ./kubesphere-images -l IMAGES-LIST : text file with list of images. -r PRIVATE-REGISTRY : target private registry:port. -s : save model will be applied. Pull the images in the IMAGES-LIST and save images as a tar.gz file. -v KUBERNETES-VERSION : download kubernetes' binaries. default: v1.17.9 -h : usage message
Pull images in
offline-installation-tool.sh
../offline-installation-tool.sh -s -l images-list.txt -d ./kubesphere-images
Note
You can choose to pull images as needed. For example, you can delete##k8s-images
and related images under it inimages-list.text
if you already have a Kubernetes cluster.
Step 2: Push Images to Your Private Registry
Transfer your packaged image file to your local machine and execute the following command to push it to the registry.
./offline-installation-tool.sh -l images-list.txt -d ./kubesphere-images -r dockerhub.kubekey.local
Note
dockerhub.kubekey.local
in the command. Make sure you use your own registry address.Step 3: Download ks-installer
Similar to installing KubeSphere on an existing Kubernetes cluster in an online environment, you also need to download kubesphere-installer.yaml
.
Execute the following command to download ks-installer and transfer it to your machine that serves as the taskbox for installation.
curl -L -O https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/kubesphere-installer.yaml
Verify that you have specified your private image registry in
spec.local_registry
incluster-configuration.yaml
. Note that if your existing cluster was installed in an air-gapped environment, you may already have this field specified. Otherwise, run the following command to editcluster-configuration.yaml
of your existing KubeSphere v3.1.x cluster and add the private image registry:kubectl edit cc -n kubesphere-system
For example,
dockerhub.kubekey.local
is the registry address in this tutorial, then use it as the value of.spec.local_registry
as below:spec: persistence: storageClass: "" authentication: jwtSecret: "" local_registry: dockerhub.kubekey.local # Add this line manually; make sure you use your own registry address.
Save
cluster-configuration.yaml
after you finish editing it. Replaceks-installer
with your own registry address with the following command:sed -i "s#^\s*image: kubesphere.*/ks-installer:.*# image: dockerhub.kubekey.local/kubesphere/ks-installer:v3.4.1#" kubesphere-installer.yaml
Warning
dockerhub.kubekey.local
is the registry address in the command. Make sure you use your own registry address.
Step 4: Upgrade KubeSphere
Execute the following command after you make sure that all steps above are completed.
kubectl apply -f kubesphere-installer.yaml
Step 5: Verify Installation
When the installation finishes, you can see the content as follows:
#####################################################
### Welcome to KubeSphere! ###
#####################################################
Console: http://192.168.0.2:30880
Account: admin
Password: P@88w0rd
NOTES:
1. After you log into the console, please check the
monitoring status of service components in
the "Cluster Management". If any service is not
ready, please wait patiently until all components
are up and running.
2. Please change the default password after login.
#####################################################
https://kubesphere.io 20xx-xx-xx xx:xx:xx
#####################################################
Now, you will be able to access the web console of KubeSphere through http://{IP}:30880
with the default account and password admin/P@88w0rd
.
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.