从 v4.1.x 离线升级到 v4.2.0

更新时间：2025-07-15 02:45:09

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

前提条件

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

注意事项

如果已在 4.1.x 版本中自定义配置过 nodeShell 镜像，升级时注意在升级配置文件 kse-v4.2.0-host-custom-values.yaml 中按照如下方式指定 nodeShell 镜像。示例如下：

若在 v4.1.x 中配置为：

nodeShell:
  image:
    registry: ""
    repository: kubesphereio/kubectl
    tag: "v1.27.12"
    pullPolicy: IfNotPresent

需在 kse-v4.2.0-host-custom-values.yaml 中配置为：

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

自 v4.1.3 起，ks-core chart 中集群角色与主集群名称配置有变更，因此从 v4.1.2 升级时注意按升级配置文件中的说明进行配置（v4.1.3 不受影响）。
```
multicluster:
  # 集群角色名称
  role: ""
  # 主集群名称（优先级：直接指定 > 从 kubesphere-config 读取 > 默认名称 host）
  hostClusterName: ""
```
自 v4.1.3 起，以下参数已废弃，升级时注意在升级配置文件 kse-v4.2.0-host-custom-values.yaml 中删除该参数或者设置为 false。
```
upgrade:
  enabled: false
```

准备工作

1. 解压安装包

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

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

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

2. 推送镜像

在 v4.2.0 目录下，编辑安装 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.2 升级至 v4.2.0 之前，应该对 KubeSphere 企业版历史版本创建的扩展组件资源进行补丁操作。

注意

该步骤仅用于 v4.1.2 → v4.2.0 的升级场景，v4.1.3 → v4.2.0 可略过该步骤。
```
# 使用安装包中 tools 目录下的 extension-resources-patch.sh 处理
bash tools/extension-resources-patch.sh
```

注意
该步骤仅用于 v4.1.2 → v4.2.0 的升级场景，v4.1.3 → v4.2.0 可略过该步骤。

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

helm get values -n kubesphere-system ks-core

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

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

cat <<EOF > kse-v4.2.0-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.2.0-host-custom-values.yaml --wait --debug

注意

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

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

检查 host 集群是否升级成功。

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

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

使用原有的 Web 控制台的 IP 地址、管理员用户名和管理员密码，并使用网页浏览器登录 v4.2.0 的 KubeSphere 企业版 Web 控制台。
检查 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.2.0-member-custom-values.yaml

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

# 替换为 member 集群的 jwtSecret 值
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.2.0-member-custom-values.yaml --wait --debug

注意

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

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

检查 member 集群是否升级成功。

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

root@xxx:~# kubectl get pod -n kubesphere-system
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	KSE v4.2.0
alloy	不涉及	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	不涉及	不涉及	0.1.0
dmp	2.1.3	2.1.4	2.2.0
edgewize	不涉及	不涉及	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	已移除（迁移至 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	不涉及	不涉及	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	不涉及	不涉及	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	不涉及	不涉及	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	不涉及	不涉及	1.0.3
wiztelemetry-tracing	不涉及	不涉及	1.0.3