简介ks-core-1.1.3.tgz 是一份面向 Kubernetes 运维与平台研发人员的 Helm Chart 资源包主要解决在离线或受控网络环境下快速部署集群核心组件、以及按需调整默认配置的问题。压缩包体积 80KB包含 120 个文件其中 yaml 文件承担工作负载与服务配置tpl 模板负责把参数渲染为最终资源清单sh 脚本封装安装、卸载等生命周期操作rego 文件用于策略评估配套的 README 与 helmignore 也让定制与发布更规范。对希望深入 K8s 生态的读者而言这份资源提供了一个结构完整、体量轻巧的真实案例可以从中学习 Helm Chart 的目录组织、变量传递和钩子脚本设计。目前已有 260 人学习/下载适合用来比对不同版本 ks-core 的差异或在本地解析扩展规则与自定义资源过滤器作为二次开发和离线部署的参考资料。1. 拿到 ks-core-1.1.3.tgz 之后先搞清楚它是什么1.1 从包名看门道tgz、版本号、组件定位先说说这个文件名的构成。ks-core-1.1.3.tgz拆开看就是三个信息ks-core是项目名1.1.3是版本号.tgz是打包格式——本质是 tar 归档后用 gzip 压缩在 Linux 服务器上最常见的那种分发格式等价于.tar.gz。对于做容器平台运维的人来说看到 tgz 基本就能猜到这八成是离线安装包或者 Helm Chart 的压缩分发版本。那么ks-core到底是什么这里要引入一个背景KubeSphere 是目前国内使用率很高的开源容器管理平台它的架构不是一个大单体而是拆成了很多组件协同工作。其中ks-core是 KubeSphere 4.x 之后的核心控制面组件负责整个平台自身的生命周期管理包括 Console 控制台、认证鉴权、多租户管理、扩展组件Extension的安装与卸载等。换句话说KubeSphere 的很多外围功能模块都是通过 ks-core 来调度安装的它相当于整个平台的操作系统内核。所以拿到这个 tgz你要做的第一件事不是急着解压而是先确认它是给什么环境用的、解决了什么问题。ks-core-1.1.3.tgz这个版本主要面向 KubeSphere 4.x 的离线部署场景适合那些网络隔离、无法直接访问公共镜像仓库的生产环境或者需要在已有 Kubernetes 集群上快速拉起一套 KubeSphere 底座的情况。你要是还在用 KubeSphere 3.x 那套 ks-installer 的方式那和 4.x 的 ks-core 完全是两条路线千万别搞混。1.2 为什么 KubeSphere 把核心能力单独打包成一个 Chart在 KubeSphere 4.x 里官方把原来 kr-installer 的职责做了拆分核心能力收敛到ks-core这个 Helm Chart 里外围功能全部改成通过扩展机制动态安装。这个设计变化其实非常关键我们作为使用者需要理解背后的逻辑否则在实际部署时很容易迷茫。第一降低安装耦合度。老版本的 KubeSphere 把监控、日志、告警、服务网格等一堆组件全部揉在安装流程里即使你只需要一个简单的多租户管理面它也把所有组件都拉起来资源占用大、失败率高。ks-core 只保留最核心的底座能力把可选组件全部后置这样安装时你只需要关注最小集跑起来之后按需再装。第二适配离线交付场景。企业内网环境普遍扫描不了外部镜像仓库而 tgz 格式的 Chart 包加配套的镜像 tar 包是现在离线交付的主流做法。官方发布 ks-core 的 tgz就是要配合helm install直接消费这个包或者通过 KubeSphere 的扩展市场在离线环境下导入。第三版本迭代更轻量。核心控制面和外围模块解耦之后升级核心组件不会牵连业务插件回滚的爆炸半径也变小了。在 1.1.3 这个版本里你可以看到 ks-core 对 Kubernetes 版本兼容性、KubeSphere 扩展 API 的稳定性都有明确的约束这些在安装前都要仔细对一遍。提示如果你拿到的是 ks-core 而不是 ks-installer说明你走的 KubeSphere 4.x 部署路线。不要在 3.x 的文档里搜安装方法也不要拿 ks-installer 的账号密码配置逻辑来套 ks-core版本不对操作全白费。2. 拆包与内容解读拿到 tgz 之后的第一件事2.1 安全校验与解包别急着 tar xf我见过不少人拿到 tgz 就直接tar xf解压然后丢到服务器上开始配这是有隐患的。一是你无法确认这个包在传输过程中有没有被篡改二是不知道 Chart 内部的 values 默认值是否符合你的集群环境。所以拿到ks-core-1.1.3.tgz之后建议先走一遍校验和解包流程。如果你是从官方 Release 页面下载的旁边通常会有对应的sha256校验值。在 Linux 上执行$ sha256sum ks-core-1.1.3.tgz把输出的哈希值和官方页面给的比对一致再继续。这一步看起来多此一举但在生产环境尤其是内网离线环境包经常是经过多次拷贝、U盘搬运、甚至通过不同网段中转的任何一步出错都可能导致安装时出现奇怪的异常。校验一次花不了十秒钟能省掉后面几小时的排查时间。校验通过后解包$ tar xzf ks-core-1.1.3.tgz $ tree -L 2 ks-core解压出来你会看到标准的 Helm Chart 目录结构核心的东西是Chart.yaml、values.yaml、templates/目录。这里我建议把Chart.yaml打开看一眼确认apiVersion、appVersion、kubeVersion这几个字段和你用的 Kubernetes 集群版本是否匹配。2.2 Chart 内部目录结构解析解压之后重点看这三个文件Chart.yaml里记录的是 Chart 元数据。ks-core-1.1.3这个包的kubeVersion约束一般是1.23.0如果你用的是 1.20 或更老的集群直接安装会报兼容性错误。这个字段是 Helm 在安装阶段就会校验的提前看清楚能避免无谓的报错。values.yaml是整个安装的核心里面定义了 ks-core 启动后的所有可调参数包括镜像仓库地址、镜像拉取策略、服务类型NodePort 还是 LoadBalancer、控制台访问地址、存储类、资源配额等。我建议在安装前完整读一遍这个文件的注释尤其是下面几个关键项imageRegistry和imagePullSecret指定镜像仓库地址和拉取凭证离线环境必须把仓库指向内网镜像源否则安装时会去公网拉镜像导致超时失败。console配置段控制台暴露方式和域名配置涉及到你之后怎么访问 KubeSphere 界面。extension配置段要不要启用扩展市场离线环境下这个通常先关闭等核心组件装好后再手动导入扩展包。templates/目录下是渲染 Kubernetes 资源的模板这个不建议改动除非你有特殊的定制需求。你要是对 Helm 模板语法不熟改坏的代价远大于收益。注意values.yaml 里改参数时注意 YAML 的缩进格式。我见过太多人因为复制粘贴时 Tab 和空格混用导致helm install的时候 YAML 解析直接报错。建议统一用两个空格缩进用vim编辑时打开set expandtab。3. 部署实操从 tgz 到一套可用的 KubeSphere3.1 环境准备与前置条件核对开始安装之前先把环境对一遍。按照我实际的部署经验需要确认以下条件第一Kubernetes 集群本身要健康。执行kubectl get nodes确保所有节点状态是 Readykubectl get pods -n kube-system看核心系统组件是否稳定。如果集群本身有问题比如 CoreDNS 挂掉、kube-proxy 异常那 ks-core 装上去也不会正常跑。第二确认有足够的资源。ks-core 最小安装大概需要 2 核 CPU、4G 内存如果还要跑 KubeSphere 的监控和日志组件建议至少准备 4 核 8G。资源不够的话安装过程中 Pod 会一直 Pending看着就像卡住了。第三确认存储类。KubeSphere 需要一套可用的 StorageClass 来创建 PVC。用kubectl get sc查看集群里有没有默认的 StorageClass如果显示none要么装一个要么在 values 里显式指定。第四准备镜像仓库。离线环境一定要有一个内网镜像仓库比如 Harbor然后把 ks-core-1.1.3 配套的镜像全部推到内网。如果官方给你的是镜像 tar 包用docker load导进来再重新 tag 推到内网仓库这一步不能省。这些前置条件看起来麻烦但每一项都是踩过坑换来的。我最早做离线部署时以为直接把包丢上去装就行结果镜像拉不下来、存储类没配、节点资源不足三个问题轮流出现装了三遍才成功。所以别嫌麻烦先花十分钟把环境对好后面一次过。3.2 使用 Helm 安装 ks-core环境准备好之后安装本身其实不复杂。先创建一个独立的命名空间建议用kubesphere-system$ kubectl create namespace kubesphere-system然后在解压出来的 ks-core 目录下用 Helm 安装$ cd ks-core $ helm install ks-core . -n kubesphere-system \ --set imageRegistryharbor.example.com/kubesphere \ --set imagePullSecretkubesphere-registry-secret \ --set console.typeNodePort \ --set console.nodePort30880这里解释一下关键的参数imageRegistry指向你内网镜像仓库的地址确保 ks-core 的所有镜像从这个源拉取。imagePullSecret如果内网仓库是私有的需要先创建这个 Secret否则 Pod 拉镜像时没权限会一直 ImagePullBackOff。console.typeNodePort和console.nodePort30880通过节点端口暴露 KubeSphere 控制台这是离线环境里最常见的访问方式。如果你在云上装了 LoadBalancer 插件也可以改成LoadBalancer模式。执行helm install后它会返回提示信息告诉你 release 的名称、命名空间、以及如何查看安装状态。等待 Pod 拉起来用下面命令观察$ kubectl get pods -n kubesphere-system -w正常情况下你会看到ks-apiserver-*、ks-console-*、ks-controller-manager-*这组 Pod 依次进入 Running 状态。等待的时间取决于内网镜像源的速度通常 1 到 3 分钟就能全部就绪。3.3 验证安装并获取初始账号安装完成后验证一下核心服务是否正常。先看 Pod 状态再用curl探测一下 API 接口$ kubectl get pods -n kubesphere-system $ curl -I http://任意节点IP:30880如果返回HTTP/1.1 200 OK说明控制台已经可以访问了。默认的初始账号是admin密码需要从 Kubernetes Secret 里取$ kubectl get secret -n kubesphere-system ks-console-secret -o jsonpath{.data.password} | base64 -d这里的逻辑是ks-core 在初始化时会自动生成一个随机密码并存入 Secret取出来就是首次登录的凭证。登录后系统会强制让你修改密码这个流程跟主流平台的初始密码逻辑一致。提示初始密码取出来建议立刻修改。另外如果是纯离线环境控制台登录后可能提示“无法访问扩展中心”这是正常的因为扩展中心需要外网连接。你需要把扩展包离线导入才能使用完整功能。4. 版本升级与回滚1.1.3 如何落位到存量环境4.1 从旧版本升级到 1.1.3如果你之前已经部署了 ks-core 的旧版本比如 1.1.2 或 1.1.1想在现有环境上升级到 1.1.3不需要卸载重装直接用 Helm 的升级命令即可。首先把新包解压出来然后执行$ helm upgrade ks-core ./ks-core -n kubesphere-system \ --set imageRegistryharbor.example.com/kubesphere \ --set imagePullSecretkubesphere-registry-secret升级前有一个非常重要的操作备份现有配置。说白一点就是把你当前的 values 参数导出来防止升级时新默认值覆盖你之前调过的参数$ helm get values ks-core -n kubesphere-system ks-core-values-backup.yaml执行升级后观察 Pod 的滚动更新情况。ks-core 的升级策略是滚动更新理论上不会中断服务但ks-apiserver重启的那几十秒里正在执行的 API 请求会短暂失败这个在业务高峰期升级时要留意。升级完成后再次验证控制台访问和 API 状态。4.2 回滚策略与数据保护升级失败怎么办Helm 天然支持版本回滚。升级前先记录一下当前 release 的版本号$ helm history ks-core -n kubesphere-system如果升级后出现异常通过--revision参数回滚到之前的版本$ helm rollback ks-core 上一个版本号 -n kubesphere-system还有一个容易被忽略的点ks-core 的配置存储在 ConfigMap 和 Secret 中升级过程中 Helm 会渲染新的配置如果新版模板对某个参数做了结构调整旧参数可能被忽略导致配置“感觉丢了”。所以回滚之后最好核对一下关键配置是否还在。另外ks-core 本身管理了 KubeSphere 的自定义资源CRD升级时如果新增了 CRDHelm 3 默认不会自动帮你删掉旧的 CRD也不会更新已有 CRD 的 schema。遇到 CRD 相关问题可能需要手动kubectl apply新包里的 CRD 文件。这一步往往是升级后出现“某些资源无法创建”的根源。注意回滚只解决 ks-core 自身的软件状态如果你在升级过程中做过 CRD 迁移或数据目录的变更回滚不会自动恢复数据。生产环境强烈建议升级前对 etcd 做一次快照备份这是 Kubernetes 集群层面的兜底手段。5. 常见问题与排查实录5.1 安装卡在等待组件就绪这是我在离线部署时遇到最多的问题。helm install执行后几个 Pod 一直处于 Pending 或 ContainerCreating 状态看起来就像卡死了一样。排查思路按顺序来第一步先看 Pod 事件$ kubectl describe pod -n kubesphere-system pod-name最常见的原因有三个节点资源不足导致 PendingPVC 无法绑定因为没有可用的 StorageClass镜像拉取失败因为镜像仓库地址配错或者没有配 Secret。这三个问题通过describe的事件输出基本都能直接看出来。第二步看 kubelet 日志。如果 ContainerCreating 卡了很久大概率是拉取镜像超时或者挂载卷失败。这种问题在公网环境不常见但在内网离线环境镜像仓库带宽低、镜像体积大就很容易触发。第三步如果所有 Pod 都卡在 Init 阶段重点看 init container 的日志一般是 ks-core 在初始化数据库或等待依赖服务就绪。5.2 镜像拉取失败的排查思路离线环境镜像拉取失败是另一个高频问题。表现形式是 Pod 状态是ImagePullBackOff执行kubectl describe pod能看到类似Failed to pull image的报错。排查方向有这么几个确认imageRegistry参数指向的地址在当前集群所有节点上都能访问。有时你只在一台节点上测试了连通性但其他节点访问不到内网仓库就会出现一部分 Pod 正常、一部分拉取失败。确认镜像仓库里确实有对应 tag 的镜像。ks-core 的镜像 tag 和 Chart 版本强关联比如v1.1.3不要想当然地用latest。确认 Secret 是否存在且有效。私有仓库的认证信息如果过期了也会报拉取失败。可以用kubectl get secret -n kubesphere-system检查必要时重新创建。如果实在排查不出给你一个笨但有效的办法手动在节点上docker pull一次对应镜像把完整的错误信息贴到搜索引擎里查比猜要快得多。5.3 控制台无法访问装好了但控制台打不开这是最后一步最容易遇到的坑。确认访问地址对不对路径、IP、端口都要核对。NodePort模式下访问的是任意节点 IP 加 NodePort不是集群内部 IP也不是 Pod IP。如果地址没问题看 Pod 日志$ kubectl logs -n kubesphere-system deploy/ks-console控制台日志里如果有connection refused或proxy error大概率是控制台连不上ks-apiserver。检查一下 Service 和 Endpoint 是否正常。我曾经遇到过一次 Control Plane 节点和 Worker 节点在安全组上没有放通 NodePort 端口结果外部一直访问不通防火墙规则把它挡掉了。还有一个容易被忽视的小问题浏览器缓存。老版本控制台的 JS 资源被浏览器缓存了导致新版本界面渲染异常。这种情况清一下缓存或者用无痕模式验证一下别一开始就怀疑服务有问题。我把这些高频问题整理成一个速查表方便你按图索骥症状可能原因处理方式Pod 一直 Pending节点资源不足 / 污点扩容节点或移除污点Pod 处于 ContainerCreatingStorageClass 不存在安装存储插件或指定可用 SCImagePullBackOff镜像仓库地址错误 / Secret 失效修正参数、重建 Secret控制台 404NodePort 端口被占用换个端口重新配置控制台可以打开但登录失败ks-apiserver 异常检查 apiserver 日志和 Service 连通性6. 一些实操心得与扩展建议最后分享几个我实际用下来的经验和建议。第一关于离线包的保存。ks-core-1.1.3.tgz这类 tgz 包体积不大但配套的镜像包往往有几个 GB最好是在内网机器上保留一份原始包和镜像包的双重备份同时记录官方发布的 sha256 值方便后续校验。第二关于配置管理。建议把安装时用的values.yaml单独存放到 Git 仓库里和集群目录分开维护。这样不管是后续升级、重建环境还是给别人交接都能快速还原你的部署基线。我吃过亏当时图省事没留 values 文件后来集群出问题要重装只能对着默认值一个个回忆之前改过什么。第三关于扩展组件。ks-core 装好后建议先别急着在生产环境装扩展先在测试环境把 KubeSphere 的扩展机制跑通一遍理解扩展包的格式和依赖关系之后再上生产。扩展包的安装顺序其实有讲究某些扩展依赖其他扩展装错顺序会有一堆奇怪的错误。第四关于日志和监控。ks-core 本身自带了一些基础状态指标但是生产环境建议还是独立部署 Prometheus 和 Loki不要依赖 KubeSphere 自带的轻量监控因为大规模集群下自带方案的性能和完整度都不够用。这个内容后续还可以这样扩展如果你对 KubeSphere 4.x 的架构感兴趣可以再深入看看它的扩展 API 定义和自定义资源模型搞懂这些之后你甚至可以基于 ks-core 的扩展机制开发自己的内部组件实现和 KubeSphere 平台的无缝集成。不过在动手之前先把基础部署和运维做扎实毕竟核心底座稳了上层才能放心盖楼。本文还有配套的精品资源点击获取