🚀 KubeSphere v3.4.1 已经发布，修复多项 bug。 请查看 Release notes → close
  • 简体中文
    • 简体中文
    1. 1.创建 KubeSphere Cloud 账户并登录。
    2. 2.在页面右上角，进入管理控制台，并点击轻量集群服务。
    3. 3.新建一个安装了 KubeSphere 的 K8s 集群。
    4. 4.使用默认账户和密码 （admin/P@88w0rd）登录 KubeSphere。
  •  Star
  1. Docs / 
  2. KubeSphere 企业版 / 
  3. 安装指南 / 
  4. 升级 KubeSphere / 
  5. 升级 KubeSphere 企业版

KubeSphere 企业版

最新更新:
    编辑

    升级 KubeSphere 企业版

    本节介绍如何在保持当前的 Kubernetes 版本不变的情况下从 KubeSphere 企业版 v3.5.0 升级到 KubeSphere 企业版 v4.1.0。

    前提条件

    • 您需要联系 KubeSphere 企业版的服务支持团队获取 KubeSphere 企业版 v4.1.0 安装包，以及 license。

    • 请确保当前 KubeSphere 企业版版本为 v3.5.0。如果您的 KubeSphere 企业版版本低于 v3.5.0，请先将 KubeSphere 企业版版本升级到 v3.5.0。

    • 请确保当前 Kubernetes 版本为 v1.21.x、v1.22.x、v1.23.x, v1.24.x, v1.25.x, v1.26.x, v1.27.x 或 v1.28.x。

    • 为避免数据丢失，请提前备份所有重要数据。

    准备工作

    1. 将 KubeSphere 企业版 v4.1.0 安装包传输到所有集群的节点上。

      说明

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

    2. 使用 backup.sh 备份系统企业空间（system-workspace）下所有项目中的关键资源，以及备份所有自定义角色及权限相关资源。

      执行以下命令开始备份。相关资源将备份至 backup-$timestamp 目录下。

      bash backup.sh

      备份完成后，如下图所示。

      backup

    3. 联系 KubeSphere 企业版的服务支持团队，根据当前集群的 cc.yaml 中的配置和 KubeSphere 组件的 patch 情况（如 cc.yaml 外的配置），确定升级时各组件使用的参数，然后创建 ks-core-values.yaml 文件。可参阅安装包中的 ks-core-values.yaml 示例文件。

      注意

      • 在 ks-core-values.yaml 文件中，可将集群中没有启用的组件设置为 enabled: false。core 和 iam 组件必须配置为 enabled: true，不可禁用。

      • 部分扩展组件在特定情况下（比如依赖外部服务的访问地址等），升级时不能使用默认配置，需手动配置一些字段。请参阅组件升级配置文档确认您的组件是否存在此问题，并在 ks-core-values.yaml 文件中做出相应修改。 请在 KubeSphere 企业版 v4.1.0 用户文档中的升级配置文档文件夹下查阅“默认配置”和“组件升级配置文档”。

    4. 将安装包中的 charts 文件夹、以及创建的 ks-core-values.yaml 文件复制到 upgrade.sh 所在的 tools 目录。

    5. 执行安装包中的脚本 pre-check.sh，检查是否满足升级条件，需确保所有检查项通过。如果检查未通过，后续升级很有可能失败。

    单集群升级

    1. 在 host 集群节点上，切换到安装包的 tools 目录（该目录需包含 charts 文件夹、ks-core-values.yaml 和 upgrade.sh）。

    2. 执行以下命令开始升级 KubeSphere 企业版。

      bash upgrade.sh host

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

      1. 执行以下命令，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

      2. 执行以下命令，如果显示如下信息，则表明 ks-core Helm Chart 已成功部署。

        root@xxx:~# helm list -n kubesphere-system
NAME    	NAMESPACE        	REVISION	UPDATED                                	STATUS  	CHART         	APP VERSION
ks-core 	kubesphere-system	6       	2024-04-09 14:54:09.349488995 +0800 CST	deployed	ks-core-1.0.0	v4.1.0

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

        root@xxx:~# kubectl -n kubesphere-system get pod
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

      4. 执行以下命令，如果所有扩展组件的状态为 Installed，表明扩展组件都已成功安装。

        root@xxx:~# kubectl get installplan
NAME            STATE
storage-utils   Installed
devops          Installed
network         Installed
...

      5. 登录 KubeSphere 企业版 Web 控制台后，点击右上角用户名 > 关于，显示的平台版本应为 v4.1.0。

    4. 使用原有的 Web 控制台的 IP 地址、管理员用户名和管理员密码，并使用网页浏览器登录 v4.1.0 的 KubeSphere 企业版 Web 控制台。

    5. 根据激活提示点击激活，导入 KubeSphere 企业版的 license。

    6. 检查 host 集群各项功能和数据是否正常。

    多集群升级

    1. 按照以上单集群升级步骤完成 host 集群的升级。

    2. 在 member 集群节点上，切换到安装包的 tools 目录（该目录需包含 charts 文件夹、ks-core-values.yaml 和 upgrade.sh）。

    3. 执行以下命令开始升级 KubeSphere 企业版。

      bash upgrade.sh member

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

      1. 执行以下命令，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

      2. 执行以下命令，如果显示如下信息，则表明 ks-core Helm Chart 已成功部署。

        root@xxx:~# helm list -n kubesphere-system
NAME    	NAMESPACE        	REVISION	UPDATED                                	STATUS  	CHART         	APP VERSION
ks-core 	kubesphere-system	6       	2024-04-09 14:54:09.349488995 +0800 CST	deployed	ks-core-1.0.0	v4.1.0

      3. 执行以下命令，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

    5. member 集群升级成功后，在 host 集群上执行以下命令，修改 member 集群的状态，以便使扩展组件 agent 调度到 member 集群上。

      kubectl get clusters.cluster.kubesphere.io {member-x} -o json | jq 'del(.status.conditions[] | select(.type=="Schedulable"))' | kubectl apply -f -
      说明

      执行 kubectl get cluster，替换 {member-x}。

      如果节点没有 jq 命令，可通过编辑集群资源的方式实现，编辑 member 集群的 status.conditions 中 type 为 Schedulable 的 condition，将其 status 设置为 True。

      kubectl edit clusters.cluster.kubesphere.io {member-x}
      status:
  conditions:
  - lastTransitionTime: "2024-04-11T09:12:22Z"
    lastUpdateTime: "2024-04-11T09:12:22Z"
    message: Cluster has been initialized
    reason: Initialized
    status: "True"
    type: Initialized
  - lastTransitionTime: "2024-04-12T07:59:14Z"
    lastUpdateTime: "2024-04-12T07:59:14Z"
    message: Cluster has joined federation control plane successfully
    status: "True"
    type: Federated
  - lastTransitionTime: "2024-04-12T08:02:56Z"
    lastUpdateTime: "2024-04-12T08:02:56Z"
    message: KS Core is available now
    reason: KSCoreReady
    status: "True"
    type: KSCoreReady
  - lastTransitionTime: "2024-04-12T08:02:56Z"
    lastUpdateTime: "2024-04-12T08:02:56Z"
    message: Not schedulable now
    reason: Upgrading
    status: "False"   # 修改此处即可
    type: Schedulable
  - lastTransitionTime: "2024-04-12T08:24:27Z"
    lastUpdateTime: "2024-04-12T08:24:27Z"
    message: Agent has connected to proxy successfully.
    status: "True"
    type: AgentAvailable
  - lastTransitionTime: "2024-04-12T08:57:40Z"
    lastUpdateTime: "2024-04-12T08:57:40Z"
    message: Cluster is available now
    reason: Ready
    status: "True"
    type: Ready

    6. 登录 host 集群的 KubeSphere 企业版 Web 控制台，进入集群管理页面，检查此 member 集群的各项功能和数据是否正常。

    7. 对下一个 member 集群继续执行以上步骤，直至完成所有集群的升级。

    升级后配置

    部分扩展组件，如 KubeSphere 网关、WhizardTelemetry 监控、WhizardTelemetry 告警管理、WhizardTelemetry 通知管理、RadonDB DMP 在升级后需进行额外配置，请参阅 KubeSphere 企业版 v4.1.0 用户文档中的升级配置文档文件夹下的组件升级配置文档进行配置。

    注意

    请务必参阅组件升级配置文档对升级后的 KubeSphere 网关 扩展组件进行配置，否则无法使用网关相关功能。

    常见问题

    无法操作未升级的 member 集群

    问题描述：host 集群升级到 v4.1.0 以后，无法在 KubeSphere 企业版 Web 控制台中查看和操作未升级的 member 集群。

    原因：v4.1.0 与 v3.5.0 有许多 API 不兼容导致。

    解决办法：

    • 尽快升级 member 集群。

    • 可在 member 集群升级前，通过 member 集群的 Web 控制台直接访问 member 集群。

    member 集群的 Web 控制台无法登录

    问题描述：在升级 member 集群前，通过 member 集群的 Web 控制台无法登录任何用户，提示"incorrect username or password"。

    原因：KubeSphere 企业版 v3.x 默认禁止直接访问 member 集群的 Web 控制台。

    解决办法：

    1. 执行以下命令，增加如下配置。

      kubectl -n kubesphere-system edit cm kubesphere-config
      authentication:
  oauthOptions:
    accessTokenMaxAge: 0
    clients:
    - name: kubesphere
      secret: kubesphere
      redirectURIs:
      - '*'

    2. 执行以下命令重启 ks-apiserver，即可登录 member 集群的 Web 控制台。

      kubectl -n kubesphere-system rollout restart deployment ks-apiserver

    升级脚本异常退出

    问题描述：升级过程中，升级脚本异常退出，升级失败。

    解决办法：执行以下命令，查看升级 Job 日志，排查升级失败原因。

    kubectl -n kubesphere-system get job/prepare-upgrade

kubectl -n kubesphere-system get pod |grep prepare-upgrade

# 查看升级Job日志
kubectl -n kubesphere-system logs prepare-upgrade-gvc6p
    kubectl -n kubesphere-system get job/ks-core-pre-upgrade

kubectl -n kubesphere-system get pod |grep ks-core-pre-upgrade

# 查看升级Job日志
kubectl -n kubesphere-system logs ks-core-pre-upgrade-4n7tp
    kubectl -n kubesphere-system get job/ks-core-post-upgrade

kubectl -n kubesphere-system get pod |grep ks-core-post-upgrade

# 查看升级Job日志
kubectl -n kubesphere-system logs ks-core-post-upgrade-4nzhk

    自定义角色的权限项为空

    问题描述：升级后，自定义角色的权限项为空，被赋予自定义角色的用户无法正常使用。

    解决办法：

    升级脚本 backup.sh 已帮助备份好自定义角色和自定义角色绑定，但由于权限变化，在升级时无法自动转换其权限，所以在升级后需要用户自行补充角色的权限。

    1. 使用升级脚本备份后，在 backup-$timestamp/kse35-backup-iam-xxx.yaml 路径下查看已经备份的自定义角色。

    2. 找到 metadata.annotations[iam.kubesphere.io/aggregation-roles]，用取到的值对比以下表格的 3.x 列中的名称，然后在 KubeSphere 企业版 Web 控制台找到对应的描述列中的权限名称。

      说明

      平台自定义角色请查阅以下平台表格，企业空间自定义角色请查阅以下企业空间表格，项目自定义角色请查阅以下项目表格，确认对应关系。

    示例：

    已经备份好的平台自定义角色 test 的信息如下

    apiVersion: iam.kubesphere.io/v1alpha2
kind: GlobalRole
metadata:
  annotations:
    iam.kubesphere.io/aggregation-roles: '["role-template-view-roles","role-template-view-users","role-template-view-basic","role-template-manage-clusters","role-template-view-clusters"]'
    kubesphere.io/alias-name: test-name
    kubesphere.io/creator: admin
  creationTimestamp: "2024-04-11T11:59:08Z"
  generation: 3
  name: test     #自定义角色的名称
  resourceVersion: "529194"
  uid: a3ad5e39-2959-4e14-aa8f-e0c0ad8e6889
rules:
    ...
    ...

    1. 取到 metadata.annotations[iam.kubesphere.io/aggregation-roles] 的值，如下：

      '["role-template-view-roles","role-template-view-users","role-template-view-basic","role-template-manage-clusters","role-template-view-clusters"]'

    2. 对比以下平台表格，metadata.annotations[iam.kubesphere.io/aggregation-roles] 的各个值在表格的 3.x 列，对应的权限项在表格的描述列，故应该勾选角色查看、用户查看、基础查看、集群管理、集群查看。但因基础查看在 4.1 列被标记为 none，所以无法勾选基础查看。

    3. 在 KubeSphere 企业版 Web 控制台的平台角色页面编辑 test 角色的权限。

      edit-permission

      勾选角色查看、用户查看、集群管理、集群查看。

      check-permission

    注意

    一些权限项在 v4.1.0 中已经移除，标记为 none。有些没有移除，但出于安全考虑无法再将此权限授权给自定义角色，标记为 can not use。标记为 none 或 can not use 的权限项，在编辑自定义角色的权限时，不能被勾选。

    平台

    描述3.x4.1

    企业空间创建

    role-template-create-workspaces

    global-create-workspaces

    应用模版管理

    role-template-manage-app-templates

    none

    集群管理

    role-template-manage-clusters

    global-manage-clusters

    平台设置管理

    role-template-manage-platform-settings

    can not use

    角色管理

    role-template-manage-roles

    can not use

    用户管理

    role-template-manage-users

    can not use

    企业空间管理

    role-template-manage-workspaces

    global-manage-workspaces

    应用查看

    role-template-view-app-templates

    none

    基础查看

    role-template-view-basic

    none

    集群查看

    role-template-view-clusters

    global-view-clusters

    角色查看

    role-template-view-roles

    global-view-roles

    用户查看

    role-template-view-users

    global-view-users

    企业空间查看

    role-template-view-workspaces

    global-view-workspaces

    企业空间

    描述3.x4.1

    DevOps 项目创建

    role-template-create-devops

    workspace-create-devops

    项目创建

    role-template-create-projects

    workspace-create-projects

    应用仓库管理

    role-template-manage-app-repos

    workspace-manage-app-repos

    应用模板管理

    role-template-manage-app-templates

    workspace-manage-app-templates

    DevOps 项目管理

    role-template-manage-devops

    workspace-manage-devops

    部门管理

    role-template-manage-groups

    none

    成员管理

    role-template-manage-members

    can not use

    项目管理

    role-template-manage-projects

    workspace-manage-projects

    角色管理

    role-template-manage-roles

    can not use

    企业空间设置管理

    role-template-manage-workspace-settings

    can not use

    应用仓库查看

    role-template-view-app-repos

    workspace-view-app-repos

    应用模版查看

    role-template-view-app-templates

    workspace-view-app-templates

    基础查看

    role-template-view-basic

    none

    DevOps 项目查看

    role-template-view-devops

    workspace-view-devops

    部门查看

    role-template-view-groups

    none

    成员查看

    role-template-view-members

    workspace-view-members

    角色查看

    role-template-view-roles

    workspace-view-roles

    企业空间设置查看

    role-template-view-workspace-settings

    can not use

    项目

    描述3.x4.1

    应用负载管理

    role-template-manage-app-workloads

    namespace-manage-app-workloads

    配置字典管理

    role-template-manage-configmaps

    namespace-manage-configmaps

    成员管理

    role-template-manage-members

    can not use

    项目设置管理

    role-template-manage-project-settings

    namespace-manage-project-settings

    角色管理

    role-template-manage-roles

    can not use

    保密字典管理

    role-template-manage-secrets

    namespace-manage-secrets

    服务账户管理

    role-template-manage-serviceaccount

    namespace-manage-serviceaccount

    持久卷声明管理

    role-template-manage-volumes

    namespace-manage-persistentvolumeclaims

    应用负载查看

    role-template-view-app-workloads

    namespace-manage-app-workloads

    基础查看

    role-template-view-basic

    none

    配置字典查看

    role-template-view-configmaps

    namespace-view-configmaps

    成员查看

    role-template-view-members

    namespace-view-members

    角色查看

    role-template-view-roles

    namespace-view-roles

    保密字典查看

    role-template-view-secrets

    namespace-view-secrets

    服务账户查看

    role-template-view-serviceaccount

    namespace-view-serviceaccount

    持久卷声明查看

    role-template-view-volumes

    namespace-view-persistentvolumeclaims

    通过邮件接收 KubeSphere 最新的技术博客与产品更新的通知


    感谢您的反馈。如果您有关于如何使用 KubeSphere 的具体问题，请在 Slack 上提问。如果您想报告问题或提出改进建议，请在 GitHub 存储库中打开问题。

    上一篇 : 设置钉钉通知
    页面内容