K8S 集群部署技能#

使用 kubeadm 部署生产级 Kubernetes 集群。

Workflow Overview#

text

用户发起部署、交付请求 → 展示流程概览 → 用户确认 → 信息收集 → 架构设计 → 技术方案（部署、测试） → 部署计划 → 执行工具 → 验证测试 → 交付报告 → 复盘总结

流程概览#

例如，当用户说"我想部署（搭建、交付）一套新的 K8S 集群"时，先展现以下流程和约束让用户确认：

---

⚠️ 重要提示#

部署新的 K8S 集群，意味着需要更高权限（root），同时机器上的数据会被清理，请确保你提供的机器列表是正确的。

---

部署流程#

阶段内容产出物阶段 0: 信息收集收集节点信息、SSH 凭证、版本要求节点清单阶段 1: 环境勘察检查 SSH 连通性、系统环境、外网访问、资源信息勘察报告阶段 2: 架构设计根据节点数量和资源设计集群架构架构设计文档、部署技术方案、测试验收方案阶段 3: 部署计划制定部署里程碑和时间计划部署计划文档阶段 4: 部署执行远程执行部署工具可用集群阶段 5: 集群验证验证集群功能正常验证报告阶段 6: 交付报告生成交付文档交付报告

当前版本约束#

限制项说明操作系统仅支持 Ubuntu部署方式仅支持 kubeadm存储不支持持久化存储配置GPU不支持 GPU 节点

用户确认#

展示流程后，询问用户：

以上是部署流程概览，是否符合您的预期？如果可以，我们开始第一阶段：信息收集。

---

Step 0: 信息收集#

获取以下信息后开始架构设计：

必需信息：

1. 节点 IP-主机名映射表（支持多种格式）：

   • JSON 格式： {"10.0.2.11":"k8s-node1","10.0.2.12":"k8s-node2","10.0.2.13":"k8s-node3"}

   • 文本文件（空格分隔）： text

     10.0.2.11 k8s-node1
     10.0.2.12 k8s-node2
     10.0.2.13 k8s-node3
     
     

   • CSV 文件： 10.0.2.11,k8s-node1

   • 表格形式：直接粘贴表格

   • AI 会自动解析并转换成 JSON 格式

2. SSH 访问方式（二选一）：

   • 方式 A：提供用户名和密码
   • 方式 B：提前配置好 SSH 信任关系（推荐）

3. K8S 版本：官方最新版

4. 软件包和镜像获取方式：

   • 外网：需要访问 pkgs.k8s.io、github.com、阿里云镜像
   • 内网：需要软件包源、容器镜像仓库

约束边界（当前版本不支持）：

• 持久化存储
• GPU 节点

示例用户输入：

text

有 3 台虚拟机：
- 10.0.2.7 (Control Plane)
- 10.0.2.8 (Worker)
- 10.0.2.9 (Worker)
SSH: worker/work@123
K8S 版本：官方最新版本(v1.35)

Step 1: 环境勘察#

根据用户提供的信息，进行环境勘察 主要检查点： SSH 登录验证 主机名 账户权限是否满足 资源是否符合信息 K8S部署前置检查

勘察报告用途 1，返回给用户确认 2，收集的信息用来做架构、部署方案的设计

Step 2: 架构设计#

生成架构设计文档，包含：

1. 集群拓扑：节点角色、IP 分配、网络规划
2. 组件版本：K8S、containerd、CNI 插件版本
3. 资源规划：节点资源分配、Pod 网段、Service 网段
4. 镜像源配置：国内环境镜像加速方案

使用 best-practice/best-practices.md 生成文档，生成文件保存在 report/ 目录中。

生成详细部署技术方案，包含：

1. 检查并修复系统配置
2. 检查并安装 containerd
3. 检查并安装 K8S 组件
4. 初始化 K8S 控制面
5. 安装 CNI 插件
6. 加入节点

使用 best-practice/best-practices.md 生成文档，生成文档保存在 report/ 目录中。

生成详细验证测试方案，包含：

1. 检查集群状态：节点标签、系统 Pod、CNI 插件；如果是 HA 验证 etcd 同步等
2. 测试应用部署：nginx、busybox
3. 测试网络状态：DNS 解析、Service 功能、应用部署访问等
4. 测试存储：emptyDir；目前不支持 PVC

使用 best-practice/best-practices.md 生成文档，生成文档保存在 report/ 目录中。

Step 3: 部署计划#

生成部署计划文档，包含：

1. 部署里程碑：各阶段目标
2. 依赖检查清单：系统要求、网络要求、资源要求
3. 风险评估：可能的问题和应对方案
4. 回滚方案：失败时的清理和重置步骤

使用 best-practice/deploy-plan.md 生成文档，生成文档保存在 report/ 目录中。

Step 4: 部署执行#

用户确认#

使用阶段式执行部署

交互规则（重要）#

强制要求

• ✅ 每个里程碑开始前通知
• ✅ 每个里程碑结束后汇报
• ✅ 等待用户确认后再继续

通知格式：

text

==========================================
🚀 开始执行 M0 - 环境检测
==========================================
正在检测 3 个节点的环境...
- SSH 连接：✅
- 系统版本：Ubuntu 24.04
- 资源配置：2核4G
...

==========================================
✅ M0 完成 - 环境检测通过
==========================================
下一步：M1 - 系统配置
回复 'y' 继续，或 'n' 暂停

问题处理规则（重要）： 遇到问题时， 不要直接陷入解决方案，先给用户提供 2-3 个方案让用户选择：

text

❌ 错误做法：
问题：DNS 解析失败
直接执行：配置 DNS 服务器...

text

✅ 正确做法：
==========================================
❌ M3 遇到问题 - DNS 解析失败
==========================================
错误：curl: (6) Could not resolve host: pkgs.k8s.io

可能的原因：
1. DNS 服务器未配置
2. 网络隔离（无法访问外网）
3. 防火墙限制

解决方案：
A. 配置 DNS 服务器（推荐）
   - 配置 8.8.8.8 或 114.114.114.114
   - 预计耗时：1-2 分钟

B. 使用离线安装包
   - 需要提前下载 K8S 安装包
   - 适合内网环境

C. 跳过此步骤，稍后手动安装
   - 你可以自己配置网络后继续

请选择：A / B / C

禁止行为：

• ❌ 不通知直接执行下一个里程碑
• ❌ 一股脑跑完全部流程
• ❌ 只在最后汇报结果
• ❌ 遇到问题直接陷入解决方案

里程碑#

里程碑脚本说明M000-survey.sh环境勘察（SSH、主机名、网络、资源）M101-system.sh系统配置检查和修正M202-containerd.shcontainerd 安装 + cgroup driver 配置M303-k8s-install.shkubeadm/kubelet/kubectl 安装M404-kubeadm-init.shControl Plane 初始化（含镜像源配置，支持 HA）M505-cni-plugin.shCNI 网络插件安装（支持 Flannel、Calico）M606-join.sh节点加入集群（支持 HA 多控制面）M707-cluster-verify.sh集群验证（支持 --namespace 参数）M808-cluster-cleanup.sh集群清理（检查状态/清理namespace/销毁集群）

Step 5: 验证测试#

按照确定的测试方案执行验收，不自动清理测试环境，等待用户确认

里程碑脚本说明M707-cluster-verify.sh集群验证（支持 --namespace 参数）

测试资源清理#

用户确认后，对进行测试的资源进行清理

里程碑脚本说明M808-cluster-cleanup.sh集群清理（检查状态/清理namespace/销毁集群）

Step 6: 交付报告#

生成交付报告文档，包含：

1. 部署概况：集群版本、节点信息、组件版本
2. 部署耗时: 各大阶段、子阶段耗时、阶段结果(与计划相比)
3. 验证结果：各项测试的结果
4. 后续建议：监控、备份、升级建议

使用 best-practice/delivery-report-template.md 生成文档，生成文档保存在 report/ 目录中。

Troubleshooting#

常见问题排查指南见 best-practice/troubleshooting-guide.md best-practice/best-practice.md

Resources#

bin/#

部署脚本，通过 SSH 远程执行。 每个脚本支持：

• 参数检查
• 错误处理
• 日志输出
• 幂等性（可重复执行）

conf/#

本技能提供的脚本需要的配置项

• 用户提供的基础信息
• 重试与超时
• 软件包源和容器镜像仓库
• K8S 参数配置(版本、Pod 网段等)
• 测试验收的配置

data/#

本技能执行过程中自动备份的文件

logs/#

执行本技能提供的工具输出的日志

report/#

产出的报告文档

best-practice/#

• best-practices.md - 最佳实践总结
• architecture-design-template.md - 架构设计模板
• troubleshooting-guide.md - 常见问题排查指南
• deploy-action-template.md - 部署方案模板
• deployment-plan-template.md - 部署计划模板
• check-testing-template.md - 测试验收模板
• delivery-report-template.md - 交付报告模板