离线升级到 v4.3.0

更新时间：2026-08-27 07:19:07

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

前提条件

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

KubeSphere 版本为 v4.1.x

1. 须知

KubeSphere v4.3.0 ks-core chart 变更内容

1.1 实验性功能扩展变更

# 4.1.x下ks-core values默认配置
experimental:
  maintenance: false

# 4.3.0下ks-core values默认配置
experimental:
  maintenance:
    enabled: false
    platformMaintenance: false
    description: ""

在升级前通过命令检查 4.1.3 版本的 experimental.maintenance。

# 检查命令
helm -n kubesphere-system get values ks-core -a | grep experimental -A 10

# 若默认为false，可忽略该项改动
# 若设置了true，自定义配置kse-v4.3.0-host-custom-values.yaml需调整：
experimental:
  validationDirective: ""
  maintenance:
    enabled: true # 修改此字段
    platformMaintenance: false
    description: ""

1.2 终端功能增强

# 4.1.x下ks-core values默认配置
nodeShell:
  image:
    registry: ""
    repository: kubesphereio/kubectl
    tag: "v1.27.12"
    pullPolicy: IfNotPresent

# 4.3.0下ks-core values默认配置
# nodeShell配置被terminal替代
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

自定义配置kse-v4.3.0-host-custom-values.yaml修改建议：

# 检查命令
helm -n kubesphere-system get values ks-core | grep nodeShell -A 5

# 若未设置nodeShell，可忽略
# 若设置了nodeShell，可移除该旧参数(nodeShell)，默认会按照4.3.0最新配置
# 如需修改，可按照上方4.3.0层级结构定制修改

1.3 镜像升级

# 4.1.x下ks-core values默认配置
redis:
  image:
    tag: 7.2.4-alpine

# 4.3.0下ks-core values默认配置
redis:
  image:
    tag: 7.2.14-alpine

自定义配置kse-v4.3.0-host-custom-values.yaml修改建议：

# 检查命令
helm -n kubesphere-system get values ks-core | grep redis -A 5

# 若未设置redis.image.tag，可忽略
# 若已设置redis.image.tag，可移除该tag，默认会按照4.3.0最新配置

1.4 v4.1.2 版本兼容

v4.1.2 版本需要对KubeSphere的扩展组件进行补丁操作

创建 extension-resources-patch.sh 脚本

#!/bin/bash

# 解决资源模板冲突
kubectl -n kubesphere-system label deploy extensions-museum app.kubernetes.io/managed-by=Helm
kubectl -n kubesphere-system annotate deploy extensions-museum meta.helm.sh/release-name=ks-core
kubectl -n kubesphere-system annotate deploy extensions-museum meta.helm.sh/release-namespace=kubesphere-system

kubectl -n kubesphere-system label service extensions-museum app.kubernetes.io/managed-by=Helm
kubectl -n kubesphere-system annotate service extensions-museum meta.helm.sh/release-name=ks-core
kubectl -n kubesphere-system annotate service extensions-museum meta.helm.sh/release-namespace=kubesphere-system

kubectl -n kubesphere-system label secret extensions-museum-certs app.kubernetes.io/managed-by=Helm
kubectl -n kubesphere-system annotate secret extensions-museum-certs meta.helm.sh/release-name=ks-core
kubectl -n kubesphere-system annotate secret extensions-museum-certs meta.helm.sh/release-namespace=kubesphere-system

# 解决 repository reference 冲突
for item in `kubectl get extensionversions.kubesphere.io -o jsonpath="{.items[*].metadata.name}"`;do kubectl patch extensionversions.kubesphere.io $item --type merge -p '{"spec":{"repository":"extensions-museum"}}';kubectl label extensionversions.kubesphere.io $item kubesphere.io/repository-ref=extensions-museum;done
for item in `kubectl get extensions.kubesphere.io -o jsonpath="{.items[*].metadata.name}"`;do kubectl label extensions.kubesphere.io $item kubesphere.io/repository-ref=extensions-museum;done

运行脚本

bash extension-resources-patch.sh

2. 升级包准备

在线环境：无需操作该步骤。

2.1 下载安装包

# ks-core 安装包
ins.qingcloud.com:/pitrix/installer/k8s/KSE/ks-extensions/ks-v4.3.0-extensions-v11.3.0.tgz
https://ins.qingcloud.com/repos/k8s/KSE/ks-extensions/ks-v4.3.0-extensions-v11.3.0.tgz
# 校验文件
ins.qingcloud.com:/pitrix/installer/k8s/KSE/ks-extensions/ks-v4.3.0-extensions-v11.3.0.sha256
https://ins.qingcloud.com/repos/k8s/KSE/ks-extensions/ks-v4.3.0-extensions-v11.3.0.sha256

校验安装包

sha256sum ks-v4.3.0-extensions-v11.3.0.tgz

2.2 解压文件

# 解压 ks-core 离线包
tar -xzvf ks-v4.3.0-extensions-v11.3.0.tgz

文件解压目录如下：

.
├── charts
│   └── ks-core-1.2.5.tgz         ------ ks-core 的 helm charts文件 (同 web-installer/kubesphere/playbooks/files/ks-core-1.2.5.tgz)
├── kubekey-artifact.tgz           ------ 用于kk 命令执行的离线包文件
├── manifests.yaml                 ------  离线包包含的清单
├── tools                          ------ 可能用到的工具
│   ├── amd64
│   │   ├── kubekey-v4.0.6-linux-amd64.tar.gz
│   │   ├── nerdctl-2.2.1-linux-amd64.tar.gz
│   │   └── oras_1.3.0_linux_amd64.tar.gz
│   └── arm64
│       ├── kubekey-v4.0.6-linux-arm64.tar.gz
│       ├── nerdctl-2.2.1-linux-arm64.tar.gz
│       └── oras_1.3.0_linux_arm64.tar.gz
└── web-installer

2.3 推送离线包镜像

2.3.1 构建离线包（已有离线包可跳过）

1. 下载 kubekey:

curl -sfL https://get-kk.kubesphere.io |  KKZONE=cn SKIP_WEB_INSTALLER=true sh -

下载后内容:

root@kk-package:/data/test# ls
kk  kubekey-v4.0.5-linux-amd64.tar.gz  package.sh

2. 创建 config.yaml 文件(示例)

apiVersion: kubekey.kubesphere.io/v1
kind: Config
spec:
  zone: "cn"
  download:
    arch:
      - amd64
      - arm64
    images:
      policy: warn
      registry: hub.kubesphere.com.cn
    storage_class:
      local:
        enabled: false
      nfs:
        enabled: false
    iso:
    charts: # 存放charts包
      - url: oci://hub.kubesphere.com.cn/kse/ks-core
        version: 1.2.4
  image_manifests: # 存放镜像
    # ks-core
    #- hub.kubesphere.com.cn/kse/ks-apiserver:v4.2.2-nexus-20260726
    #- hub.kubesphere.com.cn/kse/ks-console:v4.2.2-nexus-20260726

3. 打包离线包

bash package.sh config.yaml

最终得到一个 artifact.tgz 文件。

2.3.2 推送离线包

1. 进入离线包目录并解压工具

KubeKey 工具位于 tools/{arch}/ 目录下，根据安装机器的架构解压对应的工具：

# 查看机器架构
uname -m

解压 KubeKey 到离线包目录：

cd artifact/
tar -zxvf tools/{arch}/kubekey-v4.x.x-linux-{arch}.tar.gz .

2. 推送镜像到私有镜像仓库

在 config.yaml 中添加私有镜像仓库信息（若资源不存在，则执行创建操作），示例：

apiVersion: kubekey.kubesphere.io/v1
kind: Config
spec:
  download:
    arch:  # 推送镜像的架构
     - amd64
     - arm64
    images:
      # 镜像检查策略。
      # warn: 如果镜像缺少某些CPU架构或操作系统，仅记录警告
      # strict: 拉取的镜像必须包含所有选定的CPU架构和操作系统，否则报错。（默认）
      policy: warn # 有些镜像可能只有amd64单架构，推送多架构镜像时请设置为 warn
  image_registry:
    auth:
      registry: dockerhub.kubekey.local # 私有镜像仓库地址，按实际情况添加项目，比如dockerhub.kubekey.local/kse。
      username: admin # 私有镜像仓库登录用户名
      password: Harbor12345 # 私有镜像仓库登录密码
      skip_tls_verify: false # 是否跳过 TLS 证书验证，默认为 false
      plain_http: false # 是否使用 HTTP 明文传输，默认为 false

执行以下命令将离线包中的镜像推送到已部署的私有镜像仓库：

./kk artifact images --push -c config.yaml -a kubekey-artifact.tgz

3. 升级前检查

3.1 备份自定义图标和主题

若自定义了平台信息（平台标识/icon/theme），但未开启ks高可用。升级后需要重新上传（在升级前，备份主题及图标）。查看ks高可用是否开启：

# 检查当前集群 ks-core 配置
helm -n kubesphere-system get values ks-core | grep ha -A 1

# 结果如下显示：
ha:
  enabled: true
# 显示true，已开启高可用，无需备份，升级不丢失
# 若显示为false，未开启高可用，升级前需手动备份，升级完毕重新上传

4. 准备各集群自定义配置

4.1 host 集群自定义配置

# 验证集群是否为待升级集群
kubectl get node

# 检查当前集群 ks-core 配置
helm get values -n kubesphere-system ks-core


# 创建升级配置文件，如果上一步中有除镜像仓库、镜像版本、cloud和upgrade之外的其它参数，请添加至以下配置文件中。
cat <<EOF > kse-v4.3.0-host-custom-values.yaml
# 以下两个参数分别用来指定 ks-core 所使用镜像以及扩展组件所使用镜像的镜像仓库地址，根据环境实际信息修改。
global:
  imageRegistry: dockerhub.kubekey.local   #按v4.3.0离线镜像推送仓库地址填写
extension:
  imageRegistry: dockerhub.kubekey.local  #按v4.3.0离线镜像推送仓库地址填写
# 开启 ks-core 组件（ks-apiserver、ks-controller-manager、ks-console）高可用，根据集群实际情况配置
ha:
  enabled: true
# 开启 redis 高可用，ks-apiserver 高可用依赖 redis，如该参数为 false，默认 kubesphere-system 下的 redis 为单副本，根据集群实际情况配置
redisHA:
  enabled: true
EOF

4.2 member 集群自定义配置

# 验证集群是否为待升级集群
kubectl get node

# 检查当前集群 ks-core 配置
helm get values -n kubesphere-system ks-core

将 自定义配置 回填到 【集群管理】 - 操作列：【编辑配置】,确保配置一致性。

5. 升级 host 集群

该步骤在 host 集群上执行，或使用 host 集群的 kubeconfig

# 验证集群是否为待升级集群
kubectl get node

# 执行升级 （注意替换为实际使用的镜像仓库）（执行升级命令后，可在新的终端窗口中执行watch kubectl get pod -n kubesphere-system 观察 kubesphere-system 下 pod 变化）
# 离线包中 ks-core 的 chart 存放于 charts 目录下，如果路径有变更，请注意替换命令中 chart 路径（charts/ks-core）为当前环境的真实路径
helm upgrade --install ks-core charts/ks-core-1.2.5.tgz -n kubesphere-system -f kse-v4.3.0-host-custom-values.yaml --wait --debug --take-ownership

# 在线升级命令(helm版本需要>=3.17.0)
# chart=oci://hub.kubesphere.com.cn/kse/ks-core
# version=1.2.5
# helm upgrade --install -n kubesphere-system --create-namespace ks-core $chart --version $version -f kse-v4.3.0-host-custom-values.yaml --wait --debug --take-ownership

升级成功如下：

需激活新版license才可使用：

NOTES:
Thank you for choosing KubeSphere Helm Chart.

Please be patient and wait for several seconds for the KubeSphere deployment to complete.

1. Wait for Deployment Completion

    Confirm that all KubeSphere components are running by executing the following command:

    kubectl get pods -n kubesphere-system

2. Access the KubeSphere Console

    Once the deployment is complete, you can access the KubeSphere console using the following URL:

    http://192.168.6.10:30880

3. Login to KubeSphere Console

    Use the following credentials to log in:

    Account: admin
    Password: P@88w0rd

NOTE: It is highly recommended to change the default password immediately after the first login.

6. 升级 member 集群

Console界面，【集群管理】 - 操作列：【升级集群】，点击 【确定】 即可完成member集群升级

7. 升级扩展组件

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

在扩展中心点击组件名称，进入组件详情页。
点击组件图标下的，选择扩展组件配置。
清空自定义配置，再输入定制化的配置，然后点击确定。
再次点击组件图标下的，选择更新。
在扩展组件更新对话框中，点击开始更新等待升级完成。

至此，KubeSphere 完成全部升级。

KubeSphere 版本为 v4.2.x