- name
- deploy-k8s-cluster
- description
- |
K8S 集群部署技能
使用 kubeadm 部署生产级 Kubernetes 集群。
Workflow Overview
用户发起部署、交付请求 → 展示流程概览 → 用户确认 → 信息收集 → 架构设计 → 技术方案（部署、测试） → 部署计划 → 执行工具 → 验证测试 → 交付报告 → 复盘总结流程概览
例如，当用户说"我想部署（搭建、交付）一套新的 K8S 集群"时，先展现以下流程和约束让用户确认：
⚠️ 重要提示
部署新的 K8S 集群，意味着需要更高权限（root），同时机器上的数据会被清理，请确保你提供的机器列表是正确的。
部署流程
| 阶段 | 内容 | 产出物 |
|---|---|---|
| 阶段 0: 信息收集 | 收集节点信息、SSH 凭证、版本要求 | 节点清单 |
| 阶段 1: 环境勘察 | 检查 SSH 连通性、系统环境、外网访问、资源信息 | 勘察报告 |
| 阶段 2: 架构设计 | 根据节点数量和资源设计集群架构 | 架构设计文档、部署技术方案、测试验收方案 |
| 阶段 3: 部署计划 | 制定部署里程碑和时间计划 | 部署计划文档 |
| 阶段 4: 部署执行 | 远程执行部署工具 | 可用集群 |
| 阶段 5: 集群验证 | 验证集群功能正常 | 验证报告 |
| 阶段 6: 交付报告 | 生成交付文档 | 交付报告 |
当前版本约束
| 限制项 | 说明 |
|---|---|
| 操作系统 | 仅支持 Ubuntu |
| 部署方式 | 仅支持 kubeadm |
| 存储 | 不支持持久化存储配置 |
| GPU | 不支持 GPU 节点 |
用户确认
展示流程后，询问用户：
以上是部署流程概览，是否符合您的预期？如果可以，我们开始第一阶段：信息收集。
Step 0: 信息收集
获取以下信息后开始架构设计：
必需信息：
- 节点 IP-主机名映射表（支持多种格式）：
- JSON 格式：{"10.0.2.11":"k8s-node1","10.0.2.12":"k8s-node2","10.0.2.13":"k8s-node3"} - 文本文件（空格分隔）：
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 格式
- SSH 访问方式（二选一）：
- 方式 A：提供用户名和密码 - 方式 B：提前配置好 SSH 信任关系（推荐）
- K8S 版本：官方最新版
- 软件包和镜像获取方式：
- 外网：需要访问 pkgs.k8s.io、github.com、阿里云镜像 - 内网：需要软件包源、容器镜像仓库
约束边界（当前版本不支持）：
- 持久化存储
- GPU 节点
示例用户输入：
有 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: 架构设计
生成架构设计文档，包含：
- 集群拓扑：节点角色、IP 分配、网络规划
- 组件版本：K8S、containerd、CNI 插件版本
- 资源规划：节点资源分配、Pod 网段、Service 网段
- 镜像源配置：国内环境镜像加速方案
使用 best-practice/best-practices.md 生成文档，生成文件保存在 report/ 目录中。
生成详细部署技术方案，包含：
- 检查并修复系统配置
- 检查并安装 containerd
- 检查并安装 K8S 组件
- 初始化 K8S 控制面
- 安装 CNI 插件
- 加入节点
使用 best-practice/best-practices.md 生成文档，生成文档保存在 report/ 目录中。
生成详细验证测试方案，包含：
- 检查集群状态：节点标签、系统 Pod、CNI 插件；如果是 HA 验证 etcd 同步等
- 测试应用部署：nginx、busybox
- 测试网络状态：DNS 解析、Service 功能、应用部署访问等
- 测试存储：emptyDir；目前不支持 PVC
使用 best-practice/best-practices.md 生成文档，生成文档保存在 report/ 目录中。
Step 3: 部署计划
生成部署计划文档，包含：
- 部署里程碑：各阶段目标
- 依赖检查清单：系统要求、网络要求、资源要求
- 风险评估：可能的问题和应对方案
- 回滚方案：失败时的清理和重置步骤
使用 best-practice/deploy-plan.md 生成文档，生成文档保存在 report/ 目录中。
Step 4: 部署执行
用户确认
使用阶段式执行部署
交互规则（重要）
强制要求
- ✅ 每个里程碑开始前通知
- ✅ 每个里程碑结束后汇报
- ✅ 等待用户确认后再继续
通知格式：
==========================================
🚀 开始执行 M0 - 环境检测
==========================================
正在检测 3 个节点的环境...
- SSH 连接：✅
- 系统版本：Ubuntu 24.04
- 资源配置：2核4G
...
==========================================
✅ M0 完成 - 环境检测通过
==========================================
下一步：M1 - 系统配置
回复 'y' 继续，或 'n' 暂停问题处理规则（重要）： 遇到问题时，不要直接陷入解决方案，先给用户提供 2-3 个方案让用户选择：
❌ 错误做法：
问题：DNS 解析失败
直接执行：配置 DNS 服务器...✅ 正确做法：
==========================================
❌ 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禁止行为：
- ❌ 不通知直接执行下一个里程碑
- ❌ 一股脑跑完全部流程
- ❌ 只在最后汇报结果
- ❌ 遇到问题直接陷入解决方案
里程碑
| 里程碑 | 脚本 | 说明 |
|---|---|---|
| M0 | 00-survey.sh | 环境勘察（SSH、主机名、网络、资源） |
| M1 | 01-system.sh | 系统配置检查和修正 |
| M2 | 02-containerd.sh | containerd 安装 + cgroup driver 配置 |
| M3 | 03-k8s-install.sh | kubeadm/kubelet/kubectl 安装 |
| M4 | 04-kubeadm-init.sh | Control Plane 初始化（含镜像源配置，支持 HA） |
| M5 | 05-cni-plugin.sh | CNI 网络插件安装（支持 Flannel、Calico） |
| M6 | 06-join.sh | 节点加入集群（支持 HA 多控制面） |
| M7 | 07-cluster-verify.sh | 集群验证（支持 --namespace 参数） |
| M8 | 08-cluster-cleanup.sh | 集群清理（检查状态/清理namespace/销毁集群） |
Step 5: 验证测试
按照确定的测试方案执行验收，不自动清理测试环境，等待用户确认
| 里程碑 | 脚本 | 说明 |
|---|---|---|
| M7 | 07-cluster-verify.sh | 集群验证（支持 --namespace 参数） |
测试资源清理
用户确认后，对进行测试的资源进行清理
| 里程碑 | 脚本 | 说明 |
|---|---|---|
| M8 | 08-cluster-cleanup.sh | 集群清理（检查状态/清理namespace/销毁集群） |
Step 6: 交付报告
生成交付报告文档，包含：
- 部署概况：集群版本、节点信息、组件版本
- 部署耗时: 各大阶段、子阶段耗时、阶段结果(与计划相比)
- 验证结果：各项测试的结果
- 后续建议：监控、备份、升级建议
使用 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- 交付报告模板