deploy-k8s-cluster

全新地、从无到有、从零开始，部署、搭建、创造、构建、安装、交付 Kubernetes（K8S）集群。 当遇到以下场景时使用此技能： (1) 用户当前没有 K8S 集群，希望从无到有、从零开始部署一套 (2) 用户希望部署、搭建、构建、创造、安装、交付一套新 K8S 环境 (3) 用户提供服务器资源（虚拟机/物理机），询问 K8S 架构设计、技术方案、部署规划、验收方案 (4) 用户可以按照技能引导、根据技能描述 或者 使用技能下的工具完成 K8S 集群的部署 (5) 排查并解决部署、交付、安装期间的问题（例如：cgroup driver、镜像拉取失败、网络插件问题等） (6) 生成交付全流程文档（架构设计、部署方案、部署计划、交付报告、复盘总结） 适用范围：基于 kubeadm 的 Ubuntu 集群部署。不支持 k3s、托管 K8S（EKS/AKS/TKE）、CentOS/RHEL。

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

禁止行为：

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

里程碑

里程碑	脚本	说明
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: 交付报告

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

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 - 交付报告模板