KubeSphere v4.1.1 变更全解析：微内核架构、API 迁移路径与多集群管理增强

KubeSphere v4.1.1 变更全解析微内核架构、API 迁移路径与多集群管理增强【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubespherev4.1.1 是 KubeSphere 基于 LuBan 微内核架构重构后的重要版本全面转向扩展化体系内置应用市场Marketplace、支持扩展中心管理与 API/UI 扩展并围绕多集群管理、终端、存储等场景交付了大量增强与修复。阅读本文你将系统掌握 v4.1.1 的核心能力变化、需要提前规划的 API 破坏性变更含新旧路径对照、已弃用 API 清单以及升级前必须了解的已知问题为从 3.x 或 4.0 升级到 v4.1.x 提供可直接落地的迁移依据。版本定位基于 LuBan 微内核架构的一次重大演进KubeSphere v4.1.1 的核心变化是把整个平台从“单体功能集合”重构为基于KubeSphere LuBan 微内核架构的扩展化体系。这一重构决定了 v4.x 系列几乎所有后续能力的形式应用市场成为内置特性Marketplace 被集成进核心发行版而非独立组件扩展中心管理扩展通过 Extensions Center 统一管理、安装和卸载扩展UI 与 API 均可扩展前端界面与后端接口都以可扩展的方式暴露第三方能力可以按扩展形态接入Resource API 支持动态扩展新的资源类型可通过扩展动态注册到 API 层。从仓库代码结构可以印证这一点skills/目录下存在大量以扩展形态组织的运维技能目录如kubesphere-gateway、whizard-logging、kubesphere-devops-pipeline等而pkg/controller/core/中的extension_controller.go、extensionversion_controller.go、installplan_controller.go等控制器正是负责扩展、扩展版本与安装计划生命周期管理的核心实现与 Changelog 中“通过扩展中心管理扩展”的描述一一对应。核心新特性Featuresv4.1.1 的新特性覆盖多集群、身份安全、终端、网关与存储等方向以下逐项结合仓库源码说明。多集群与身份管理支持通过 kubeconfig 一键导入成员集群成员集群接入不再依赖复杂的手动配置只需提供 kubeconfig 即可完成导入。支持 KubeSphere Service Accounts为工作负载或自动化流程提供独立于平台用户的服务账号身份。在pkg/controller/ksserviceaccount/下可以找到serviceaccount_controller.go与pod_injector.go前者负责服务账号生命周期管理后者负责向 Pod 注入对应凭据这正是该特性的底层支撑。支持将集群、工作空间、项目加入快捷访问工作台Workbench与快速入口的可用性显著提升工作台页面本身也在本次版本中做了重构。终端能力容器终端支持文件上传与下载在pkg/kapis/terminal/v1alpha2/register.go中可以看到对应 API 路由POST /namespaces/{namespace}/pods/{pod}/file上传文件到 Pod与GET /namespaces/{namespace}/pods/{pod}/file从 Pod 下载文件两者都支持通过查询参数container指定容器、path指定目标路径。同时该注册文件还定义了上传文件大小上限的解析逻辑默认UploadFileLimit为 100 MB100 20若配置解析失败会回退到默认值 100Mi并记录告警日志pkg/kapis/terminal/v1alpha2/register.go#L33-L40。网关与存储适配各厂商云原生网关Kubernetes Ingress API网关能力向标准 Kubernetes Ingress API 对齐v4.1 中网关相关的gateway.kubesphere.io/v1alpha1API 被移除查询 Ingress 配置关联网关的接口调整为/kapis/gateway.kubesphere.io/v1alpha2/namespaces/{namespace}/availableingressclassscopes详见下文 API 变更章节。支持 API 速率限制平台级 API 增加限流能力防止单个调用方过度消耗 apiserver 资源。支持在页面上创建持久卷PV存储管理从“只消费”走向“可供给”配合本次同时修复的“基于快照创建 PVC 失败”“持久卷列表状态显示错误”等问题存储链路整体更完整。增强Enhancementsv4.1.1 的增强项集中在多集群运维效率与细节体验上方向增强内容工作空间创建工作空间时支持一次性选择所有集群Web kubectl支持切换集群时动态回收 Pod、支持模糊搜索节点列表默认排序改为升序支持列表页水平移动横向滚动OAuth 安全仅允许受信任的 OAuth 客户端直接使用用户名密码校验用户身份成员集群精简 Agent 组件、简化 Agent 部署方式支持主动触发集群资源同步配置管理将 KubeSphere Config 中的部分配置拆分为独立配置项ConfigMap 详情支持展示binaryData镜像与调度容器镜像搜索结果按时间倒序排列集群列表展示调度状态用户管理支持编辑用户别名工作负载集群下工作负载页面、应用列表、PVC 与存储类列表的体验优化超长资源名称显示优化稳定性支持全局启用fieldValidation控制面节点可禁用终端交付支持通过 helm 快速部署与卸载其中“仅允许受信任的 OAuth 客户端直接使用用户名密码校验身份”是安全敏感变更从 v4.1.1 起未纳入信任列表的 OAuth 客户端将不能绕过 OAuth 授权流程直接用账号密码换取身份使用自定义 OAuth Client 对接第三方系统时需要在 OAuth 客户端配置中显式声明信任关系。Bug 修复按模块归类v4.1.1 修复了大量问题按模块归类便于排查历史故障是否属于已知缺陷终端与会话修复节点终端无限显示 “connecting” 的问题修复关闭 kubectl 容器终端时对应 Pod 未被终止的问题修复 EKS 环境下 web kubectl 终端不可用的问题修复控制台首次登录白屏与页面重定向错误的问题修复配置错误导致会话异常登出的问题。多集群修复以 cluster-admin 登录时找不到集群管理入口的问题修复下载 kubeconfig 时无法选择集群的问题修复添加成员集群时页面不实时刷新的问题修复选择集群时不按用户权限过滤集群的问题修复集群管理页移除未就绪集群时弹窗与进度条显示异常的问题修复“为集群添加标签”弹窗中搜索后已选集群选中态丢失的问题修复集群列表搜索集群时显示异常的问题。权限与安全修复工作空间中资源被未授权访问的潜在问题修复工作空间中集群授权 API 被未授权访问的潜在问题修复 helm 应用部署中潜在的权限提升与授权风险修复未授权用户从应用商店部署应用时白屏的问题。应用与仓库修复应用模板创建时文件上传卡死的问题修复一个项目中的应用在其他项目可见的问题修复应用仓库中 bitnami 源无法同步的问题修复应用模板显示无数据的问题。存储与 ConfigMap/Secret修复基于快照创建 PVC 失败的问题修复持久卷列表状态显示错误的问题移除持久卷扩容时多余的操作提示修复编辑 Secret 时丢失 ownerReferences 的问题修复成员集群 ConfigMap 无法编辑设置、无法编辑或删除键值对数据的问题修复创建 Secret 时类型下拉框显示错误、选择 “Image registry information” 类型时数据填充错误、Secret 类型显示错误的问题修复创建 Secret 选择 HTTPS 镜像仓库地址时默认跳过证书校验的问题。镜像与工作负载修复无法搜索 Harbor2.8.0 及以上版本镜像的问题修复添加镜像服务信息从指定仓库拉取镜像时异常的问题修复工作负载详情页 Pod 分页问题修复工作负载列表无法获取全部项目的问题修复工作负载中 Pod 提示信息显示异常的问题。其他修复节点删除标签异常的问题修复 CRD 页面展示的版本不是最新版本的问题修复控制台 HTTPS 协议下加载缓慢的问题修复 Windows 环境下复选框滚动问题修复部分页面翻译缺失、容器详情页空白显示、列表页悬浮元素显示不完整、右上角错误提示显示异常等问题修复创建工作空间弹窗显示异常、工作空间列表显示异常、容器内上传文件缺提示等问题修复从 3.x 场景迁移的用户可能关心的 “指定集群创建者为集群管理员” 默认行为问题默认将集群创建者指定为集群管理员。API 变更升级前必须完成的迁移清单这是 v4.1 升级中最关键的部分。以下 API 将在v4.1 中移除依赖它们的脚本、扩展或二次开发代码必须先行迁移。多集群代理路径规则调整旧的代理请求 API/API_PREFIX/clusters/{cluster}/API_GROUP/API_VERSION/...已移除请改用新的路径规则/clusters/{cluster}/API_PREFIX/API_GROUP/API_VERSION/...即{cluster}段之后必须先跟 API 前缀如api、apis、kapis再跟 API 分组与版本。仓库中多集群代理过滤器pkg/apiserver/filters/multicluster.go的核心逻辑正是解析请求路径中clusters/{cluster}段第 43 行注释明确说明该段含义并在代理转发前将其剥离第 79、96 行随后决定走 kube-apiserver 代理还是 ks-apiserver 代理第 107-146 行实际代理通过proxy.NewUpgradeAwareHandler实现并支持 WebSocket 升级第 155-156 行。路径前缀顺序的变化直接作用于这段解析逻辑调用方务必按新规则拼接 URL。访问控制Access Controliam.kubesphere.io/v1alpha2API 版本已移除请改用iam.kubesphere.io/v1beta1。仓库中iam分组同时保留v1alpha2与v1beta1两个版本目录staging/src/kubesphere.io/api/iam/其中v1beta1已通过kubebuilder:storageversion标记为存储版本staging/src/kubesphere.io/api/iam/v1beta1/types.gov1alpha2目录仅保留旧类型定义用于兼容读取。iam.kubesphere.io/v1beta1的重大变化Role、RoleBinding、ClusterRole、ClusterRoleBinding 这几类资源的 API Group 从rbac.authorization.k8s.io变更为iam.kubesphere.io。这意味着所有基于原生 RBAC 对象编写的 RBAC 相关代码授权检查、角色绑定操作都需要切换到新的 Group同时平台自身的授权层pkg/apiserver/authorization/下的 authorizer、rbac 实现也围绕新的 iam 语义工作自定义授权逻辑若直接构造rbac.authorization.k8s.io资源将不再被识别。多租户Multi-tenancytenant.kubesphere.io/v1alpha1与tenant.kubesphere.io/v1alpha2的部分 API 已移除请改用tenant.kubesphere.io/v1beta1。仓库中三个版本目录并存staging/src/kubesphere.io/api/tenant/v1beta1为存储版本types.go 中kubebuilder:storageversion。tenant.kubesphere.io/v1beta1的重大变化Workspace的spec.networkIsolation字段已被移除。查看 staging/src/kubesphere.io/api/tenant/v1beta1/types.go 可以看到v1beta1 的WorkspaceSpec目前仅保留Manager字段第 24-27 行网络隔离能力已不在 Workspace 核心对象上提供——这与“已知问题”中“Network isolation网络隔离暂时不可用将由扩展提供”的说明一致。kubectl 与终端/resources.kubesphere.io/v1alpha2/users/{user}/kubectl接口已移除终端相关操作不再需要调用该接口。用户 web kubectl 终端的 API 路径已调整旧路径/kapis/terminal.kubesphere.io/v1alpha2/namespaces/{namespace}/pods/{pod}/exec新路径/kapis/terminal.kubesphere.io/v1alpha2/users/{user}/kubectl仓库中的路由注册文件pkg/kapis/terminal/v1alpha2/register.go同时保留了/namespaces/{namespace}/pods/{pod}/exec创建 Pod 终端会话、/nodes/{nodename}/exec节点 shell 访问与/users/{user}/kubectl为当前用户创建 kubectl 终端会话等多条路由说明“按 Pod 开终端”与“按用户开 kubectl 终端”被明确区分为两类能力前端入口已迁移到users/{user}/kubectl。网关Gatewaygateway.kubesphere.io/v1alpha1API 版本已移除。仓库中网关 API 目前保留v1alpha2版本staging/src/kubesphere.io/api/gateway/v1alpha2/。查询 Ingress 配置关联网关的 API 已调整为/kapis/gateway.kubesphere.io/v1alpha2/namespaces/{namespace}/availableingressclassscopes。已弃用 API将在未来版本移除以下 API 已在 v4.1 标记为 deprecated建议新代码不再使用并规划后续迁移弃用 API说明Cluster validation API集群校验接口Config configz API配置中心 configz 接口OAuth token review APIOAuth Token 校验接口Operations job rerun API运维任务重跑接口Resources v1alpha2 API资源接口 v1alpha2Resources v1alpha3 API资源接口 v1alpha3Tenant v1alpha3 API租户接口 v1alpha3Legacy version API遗留版本接口已知问题与能力迁移路径升级与使用前需明确以下限制这些内容在 CHANGELOG-4.1.1.md 中被官方明确记录升级限制目前不支持从 3.x 直接升级到 4.x该能力将在后续版本中提供。3.x 用户需规划全新部署或等待官方升级通道。暂不可用、将由扩展提供的能力监控Monitoring告警Alerting通知NotificationsIstio服务网格DevOps项目网关与集群网关Project/Cluster Gateway存储卷快照Storage Volume Snapshot网络隔离Network IsolationOpenPitrix 应用管理这些能力正是前述“扩展中心”“扩展化架构”的用武之地在 v4.1.1 中它们不再内置于核心而是以扩展形态交付安装对应扩展后即可恢复使用。暂不可用、将在后续版本支持的能力工作空间中的部门管理Department management其他调整Misc语言选项默认移除除英文和简体中文之外的所有语言选项多语言环境需在部署配置中自行开启。系统组件相关内容移除了与系统组件相关的内容平台架构更聚焦于扩展化的核心 组件组合。升级与迁移建议结合上文v4.1.1 升级落地时建议按以下顺序检查核对 API 依赖逐一扫描脚本、CI、扩展代码中是否使用了被移除的iam.kubesphere.io/v1alpha2、tenant.kubesphere.io/v1alpha1/v1alpha2、gateway.kubesphere.io/v1alpha1以及旧的多集群代理路径{API_PREFIX}/clusters/{cluster}/...全部切换到新版本与新路径调整 RBAC 对象 GroupRole / ClusterRole / RoleBinding / ClusterRoleBinding 的 API Group 已切到iam.kubesphere.io需更新所有面向rbac.authorization.k8s.io的清单与代码更新终端集成用户 web kubectl 入口改用/kapis/terminal.kubesphere.io/v1alpha2/users/{user}/kubectl确认扩展安装监控、告警、DevOps 等能力需要以扩展形式安装确保扩展中心可用并安装所需扩展确认语言与存储行为默认仅中英文PV 创建、ConfigMapbinaryData、镜像搜索排序等行为变化按需在团队内同步规避已知问题3.x 无法直接升级网络隔离、部门管理等能力暂缺避免在方案设计中依赖这些功能。v4.1.1 是 KubeSphere 全面转向 LuBan 微内核与扩展化体系的标志性版本核心变得更轻、能力以扩展交付、API 语义向标准化收敛。对平台管理员而言本文列出的 API 迁移清单与已知问题是升级前必须完成的功课对扩展开发者而言pkg/controller/core/的扩展生命周期控制器与staging/src/kubesphere.io/api/下各 API 组的版本演进则是理解 v4.1 扩展机制的最佳源码入口。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考