# Kubernetes 管理设计说明

> 更新：2026-07-05
> 范围：K8s 集群接入、自研 HTTP 客户端、资源管理、Pod exec/logs/files、YAML 编辑、事件、容量、AI 排障。// Logan.Li

---

## 定位

Kubernetes 管理模块提供多集群资源管理和排障能力。AIOps 当前采用自研轻量 K8s HTTP 客户端，不引入 client-go，重点控制镜像体积和调用边界。

---

## 能力矩阵

| 能力 | 当前状态 | 说明 |
|------|----------|------|
| 集群接入 | 已完成 | kubeconfig/API Server/TLS |
| 节点/Pod/Workload | 已完成 | 列表、详情、指标、事件 |
| Namespace 管理 | 已完成 | 命名空间资源视图 |
| YAML 查看/编辑 | 已完成 | CodeMirror、可视化编辑、导入 |
| Pod 日志 | 已完成 | 日志查看 |
| Pod exec | 已完成 | xterm + channel.k8s.io |
| Pod 文件 | 已完成 | 文件浏览、上传/下载 |
| kubectl 终端 | 已完成 | 集群级 kubectl shell |
| HPA/CronHPA | 已完成 | 工作负载扩缩容能力 |
| 集群对比/容量 | 已完成 | 多集群视图 |
| AI K8s 排障 | 已完成 | Agent CLI kubernetes 模式 |

---

## 主要代码落点

| 模块 | 后端 | 前端 |
|------|------|------|
| 集群管理 | `k8s_cluster.go`、`kubernetes.go` | `KubernetesClusters.tsx` |
| 节点/Pod/Workload | `k8s_node.go`、`k8s_pod.go`、`k8s_workload.go` | `KubernetesNodes.tsx`、`WorkloadViewPage.tsx` |
| Namespace | `k8s_namespace.go` | `NamespaceManagementPage.tsx` |
| YAML | `k8s_yaml.go`、`k8s_resource.go` | `YamlViewer.tsx`、`ResourceVisualEditor.tsx` |
| Pod exec/logs/files | `k8s_pod.go`、`k8s_pod_files.go` | `PodExecTerminal.tsx`、`PodLogsViewer.tsx`、`PodFileBrowser.tsx` |
| kubectl | `kubectl_shell.go` | `KubectlTerminal.tsx` |
| 事件 | `k8s_events.go` | `EventTable.tsx`、`EventsPage.tsx` |
| AI K8s | `agent_cli_kubernetes.go` | `AgentCLI.tsx` |

---

## 自研客户端边界

```text
AIOps Backend
  ├── build K8s request
  ├── attach token/cert
  ├── optional InsecureSkipVerify / CA
  ├── call Kubernetes API
  ├── normalize response
  └── return frontend DTO
```

原则：

- 普通资源查询走 HTTP JSON。
- Pod exec 使用 `channel.k8s.io` WebSocket。
- 文件操作优先复用 exec/tar 或 API 能力。
- 不把 kubeconfig 明文返回前端。

---

## Pod exec 通道

| Channel | 含义 |
|---------|------|
| 0 | stdin |
| 1 | stdout |
| 2 | stderr |
| 3 | error/status |
| 4 | resize |

终端通用实现见 [docs/terminal](../terminal/implementation-spec.md)。

---

## YAML 管理风险边界

高风险操作：

- delete pod/deployment/service/configmap/secret
- scale 到 0 或异常副本数
- rollout restart 生产工作负载
- 修改镜像、环境变量、挂载、权限上下文

建议接入：

1. diff 预览。
2. 风险提示。
3. 生产 namespace 审批。
4. 操作审计。
5. 回滚建议。

---

## AI K8s 排障

Agent CLI K8s 模式可用工具：

| 工具 | 用途 |
|------|------|
| `kubernetes_get` | 查询资源 |
| `pod_logs` | 查看日志 |
| `pod_execute` | 容器内执行 |
| `kubernetes_action` | 资源变更，高危确认 |

建议 Prompt 注入：

- 集群、namespace、Pod、container。
- Pod restart count。
- 最近事件。
- 所属 Deployment/StatefulSet。
- Service/Ingress 关系。
- HPA 状态。

---

## 验收清单

1. 集群配置保存后能列出 namespace/node/pod。
2. Pod 日志能实时查看并切换容器。
3. Pod exec 能 resize，Ctrl+C 可用。
4. YAML 编辑有 diff，失败时错误明确。
5. kubectl 终端关闭后后端进程清理。
6. 无权限用户不能访问未授权集群。
7. AI K8s 高危操作触发确认或审批。