back
loading skill details...
全新地、从无到有、从零开始，部署、搭建、创造、构建、安装、交付 Kubernetes（K8S）集群。 当遇到以下场景时使用此技能： (1) 用户当前没有 K8S 集群，希望从无到有、从零开始部署一套 (2) 用户希望部署、搭建、构建、创造、安装、交付一套新 K8S 环境 (3) 用户提供服务器资源（虚拟机/物理机...
---
name: deploy-k8s-cluster
description: |
全新地、从无到有、从零开始，部署、搭建、创造、构建、安装、交付 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
```
用户发起部署、交付请求 → 展示流程概览 → 用户确认 → 信息收集 → 架构设计 → 技术方案（部署、测试） → 部署计划 → 执行工具 → 验证测试 → 交付报告 → 复盘总结
```
## 流程概览
例如，当用户说"我想部署（搭建、交付）一套新的 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"}`
- 文本文件（空格分隔）：
```
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 节点
**示例用户输入**：
```
有 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. **检查并修复系统配置**
3. **检查并安装 containerd**
4. **检查并安装 K8S 组件**
5. **初始化 K8S 控制面**
6. **安装 CNI 插件**
7. **加入节点**
使用 `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: 部署执行
### 用户确认
使用阶段式执行部署
### 交互规则（重要）
**强制要求**
- ✅ 每个里程碑开始前通知
- ✅ 每个里程碑结束后汇报
- ✅ 等待用户确认后再继续
**通知格式**：
```
==========================================
🚀 开始执行 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: 交付报告
生成交付报告文档，包含：
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` - 交付报告模板don't have the plugin yet? install it then click "run inline in claude" again.