离线升级到 v4.2.1

更新时间：2026-01-14 06:02:58

本节介绍在无法访问 Internet 的情况下如何从 KubeSphere v4.1.x 或 v4.2.x 升级到 v4.2.1。

前提条件

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

注意事项

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

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

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

需在 kse-v4.2.1-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.1-host-custom-values.yaml 中删除该参数或者设置为 false。
```
upgrade:
  enabled: false
```

准备工作

1. 解压安装包

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

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

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

2. 推送镜像

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

注意

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

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

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

helm get values -n kubesphere-system ks-core

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

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

cat <<EOF > kse-v4.2.1-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.1-host-custom-values.yaml --wait --debug --take-ownership

注意

注意
helm 版本需要 >= 3.17.0 替换 `charts/ks-core` 为当前环境下 ks-core chart 的真实路径。

helm 版本需要 >= 3.17.0
替换 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.1 的 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.1-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.1-member-custom-values.yaml --wait --debug --take-ownership

注意

注意
helm 版本需要 >= 3.17.0 替换 `charts/ks-core` 为当前环境下 ks-core chart 的真实路径。

helm 版本需要 >= 3.17.0
替换 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 完成全部升级。