从 v4.1.2 离线升级到 v4.1.3

更新时间：2025-05-07 02:21:04

本节介绍如何在无法访问 Internet 的情况下从 KubeSphere 企业版 v4.1.2 离线升级到 KubeSphere 企业版 v4.1.3。

前提条件

联系 KubeSphere 企业版交付服务专家获取 KubeSphere 企业版 v4.1.3 安装包。
请确保当前 KubeSphere 企业版版本为 v4.1.2。
请确保当前 Kubernetes 版本为 v1.21.x ~ v1.30.x。
若扩展组件有特殊配置，需备份扩展组件配置。在“扩展组件配置”对话框中，下载文件备份。
为避免数据丢失，请提前备份所有重要数据。

准备工作

1. 解压安装包

将 KubeSphere 企业版安装包传输到待升级集群的节点，并登录该集群节点。
执行以下命令解压 v4.1.3 安装包（将 <package name> 替换为安装包的实际名称）。
tar -zxvf <package name>
注意

请确保操作目录有足够的可用空间，建议大于 100 GB。
进入安装包解压后生成的目录（将 <directory> 替换为安装包解压后生成的目录）。
cd <directory>
说明

若想了解安装包各个文件的作用，请参阅查看安装包内容。

注意
请确保操作目录有足够的可用空间，建议大于 100 GB。

说明
若想了解安装包各个文件的作用，请参阅查看安装包内容。

2. 推送镜像

在 v4.1.3 目录下，编辑安装 KubeSphere 企业版时创建的 config-sample.yaml 文件，修改其中的 registry 部分。

    privateRegistry: "dockerhub.kubekey.local/kse" # 替换为实际镜像仓库地址
    auths:
      "dockerhub.kubekey.local":  # 替换为实际镜像仓库地址
        username: admin           # 替换为镜像仓库的用户名
        password: Harbor12345     # 替换为镜像仓库的密码
        skipTLSVerify: true
        plainHTTP: true   # 如果镜像仓库使用 http，该参数设置为 true

推送镜像到所使用的镜像仓库。

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

升级 KubeSphere 企业版

KubeSphere 企业版 v4.1 及后续版本采用 helm chart 方式升级 ks-core。

升级 host 集群

确认当前集群为待升级集群。
```
kubectl get node -o wide
```
KubeSphere 企业版 v4.1.3 移除了 kse-extensions-publish，将其整合到了 ks-core 的 chart 中，因此在升级至 v4.1.3 之前，应该对 KubeSphere 企业版历史版本创建的扩展组件资源进行补丁操作。
```
# 使用安装包中 tools 目录下的 extension-resources-patch.sh 处理
bash tools/extension-resources-patch.sh
```

检查当前集群的 ks-core 配置。

helm get values -n kubesphere-system ks-core

创建升级配置文件，输入以下内容。

如果上一步中有除镜像仓库、镜像版本、cloud 和 upgrade 之外的其它参数，请一并添加至以下配置文件中。

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

# 以下两个参数分别用来指定 ks-core 所使用镜像以及扩展组件所使用镜像的镜像仓库地址
# 请根据环境实际信息修改
global:
  imageRegistry: dockerhub.kubekey.local/kse
extension:
  imageRegistry: dockerhub.kubekey.local/kse

# 注意集群角色参数由 role 变更为 multicluster.role
multicluster:
  role: host

# 开启 ks-core 组件（ks-apiserver、ks-controller-manager、ks-console）的高可用
# 请根据集群实际情况配置
ha:
  enabled: false

# 开启 redis 高可用，ks-apiserver 高可用依赖 redis
# 如该参数为 false，默认 kubesphere-system 下的 redis 为单副本，请根据集群实际情况配置
redisHA:
  enabled: false
EOF

执行以下命令开始升级。

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

注意

注意
替换 `charts/ks-core` 为当前环境下 ks-core chart 的真实路径。

替换 charts/ks-core 为当前环境下 ks-core chart 的真实路径。

参考以下步骤，检查 host 集群是否升级成功。

执行以下命令，upgrade job 应该是成功完成的状态，如下所示。

root@xxx:~# kubectl -n kubesphere-system get job | grep upgrade
ks-core-post-upgrade    1/1           16s        28m
ks-core-pre-upgrade     1/1           58s        31m
prepare-upgrade         1/1           26s        32m

执行以下命令，pod（ks-apiserver, ks-console, ks-controller-manager）应该为 running 状态，如下所示。

root@xxx:~# watch kubectl get pod -n kubesphere-system
NAME                                     READY   STATUS      RESTARTS        AGE
ks-apiserver-594bb884db-phrlv            1/1     Running     0               28m
ks-console-7cd55dd9f9-f2jl9              1/1     Running     0               28m
ks-controller-manager-785fc676dc-9d9j2   1/1     Running     0               28m

使用原有的 Web 控制台的 IP 地址、管理员用户名和管理员密码，并使用网页浏览器登录 v4.1.3 的 KubeSphere 企业版 Web 控制台。
根据激活提示点击激活，导入 KubeSphere 企业版的 license。
检查 host 集群各项功能和数据是否正常。

升级 member 集群

升级 member 集群与升级 host 集群的步骤基本一致，但需注意 member 集群中的特殊参数配置。

确认当前 member 集群为待升级集群。
```
kubectl get node -o wide
```

检查 member 集群的 ks-core 配置。

helm get values -n kubesphere-system ks-core

获取 member 集群的 jwtSecret 值。

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

创建升级配置文件，输入以下内容。

如果上一步中有除镜像仓库、镜像版本、cloud 和 upgrade 之外的其它参数，请一并添加至以下配置文件中。

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

# 以下两个参数分别用来指定 ks-core 所使用镜像以及扩展组件所使用镜像的镜像仓库地址
# 请根据环境实际信息修改
global:
  imageRegistry: dockerhub.kubekey.local/kse
authentication:
  issuer:
    jwtSecret: <REPLACE_ME> # 注意替换

# 注意集群角色参数由 role 变更为 multicluster.role
multicluster:
  role: member
EOF

执行以下命令开始升级。

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

注意

注意
替换 `charts/ks-core` 为当前环境下 ks-core chart 的真实路径。

替换 charts/ks-core 为当前环境下 ks-core chart 的真实路径。

参考以下步骤，检查 member 集群是否升级成功。

执行以下命令，upgrade job 应该是成功完成的状态，如下所示。

root@xxx:~# kubectl -n kubesphere-system get job | grep upgrade
ks-core-post-upgrade    1/1           16s        28m
ks-core-pre-upgrade     1/1           58s        31m
prepare-upgrade         1/1           26s        32m

执行以下命令，ks-agent pod 应该为 running 状态，如下所示。

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

如果您在以上升级命令中增加了自定义配置（如，--set a=b），需在 Web 控制台同步添加 member 集群的自定义配置。

方法：在集群管理页面，在需要操作的集群右侧点击，然后在下拉列表中选择编辑配置。在弹窗中，输入 a: b。

说明

如果您在升级命令中未加入自定义的配置，则无需在 Web 控制台添加集群配置。

说明
如果您在升级命令中未加入自定义的配置，则无需在 Web 控制台添加集群配置。

升级扩展组件

在扩展中心升级所需的扩展组件。对于已备份特殊配置的扩展组件，需先修改配置后再升级。

在扩展中心点击组件名称，进入组件详情页。
点击组件图标下的，选择扩展组件配置。
在扩展组件配置对话框中，点击恢复推荐配置，然后在默认配置中手动修改为定制化的配置，点击确定。
再次点击组件图标下的，选择更新。
在扩展组件更新对话框中，点击开始更新等待升级完成。

至此，KubeSphere 企业版完成全部升级。

可升级扩展组件列表

扩展组件	KSE v4.1.2	KSE v4.1.3
devops	1.1.1	1.1.2
dmp	2.1.3	2.1.4
gatekeeper	1.0.1	1.0.3
gateway	1.0.2	1.0.3
grafana	10.4.3	10.4.14
openpitrix	2.0.1	2.0.2
servicemesh	1.0.0	1.0.1
whizard-alerting	1.0.3	1.0.4
whizard-auditing	1.2.0	1.2.1
whizard-events	1.2.0	1.2.1
whizard-logging	1.2.2	1.2.3
whizard-notification	2.5.9	2.6.0
whizard-telemetry	1.2.2	1.3.0