内容
# kube-agents
基于 [tRPC-Agent-Go](https://github.com/trpc-group/trpc-agent-go) 和 DeepSeek 构建的 AI 驱动的 Kubernetes 运维助手。
用自然语言描述 Kubernetes 资源 - 代理理解意图，调用合适的工具，并通过 Kubernetes API 执行。
```
> 列出 default 命名空间中 Running 状态的 pod
default 命名空间 Running 状态的 Pod：
1. ba-0223-app-ccp-r5t67 IP: 10.240.147.181 节点: worker07
2. ks-web-z5t2q IP: 10.240.179.59 节点: worker04
3. nacos-register-hlbgb IP: 10.240.179.52 节点: worker04
4. txc-go-gin-grckt IP: 10.240.50.180 节点: worker02
共 4 个 Pod 处于 Running 状态。
```
## 功能
| 类别 | 能力 |
|----------|------------|
| **Kubernetes 运维** | 27 个内置工具，涵盖 pod、deployment、service、ingress、HPA、ConfigMap、Secret、namespace、event、node、通用资源 |
| **LLM 后端** | DeepSeek（默认），任何 OpenAI 兼容模型 |
| **认证授权** | Kubernetes ServiceAccount TokenReview + SubjectAccessReview；JWT 可扩展 |
| **HTTP API** | OpenAI 兼容的 `POST /v1/chat/completions`（非流式 + SSE 流式） |
| **A2A 协议** | 代理到代理的 `message/send` + `message/stream` JSON-RPC 2.0 端点 |
| **命令行界面** | `chat`（交互式），`serve`（API 服务器），`version`（表格输出）通过 cobra |
| **插件** | 内置审计、限速、日志记录；通过 `plugin.Plugin` 接口自定义 |
| **MCP** | 通过 stdio / SSE / 流式传输的外部工具服务器 |
| **技能** | 可重用的 SKILL.md 工作流程：诊断、部署、安全审计 |
| **RAG 知识** | 基于 Kubernetes 文档的语义搜索；运行时文件上传 API |
| **会话管理** | 可恢复的会话，带有 `--session-id`/`--continue`；通过 API 列出/删除 |
| **内存** | 长期用户偏好跟踪（内存 / Redis） |
| **日志记录** | `log/slog` 结构化日志记录：JSON/文本、级别、文件旋转（lumberjack） |
| **优雅关闭** | HTTP 服务器排空飞行中的请求；可配置超时 |
| **无分发镜像** | 多阶段 Docker 构建，以非 root 用户运行 |
## 快速入门
### 先决条件
- Go 1.21+
- DeepSeek API 密钥（或 OpenAI 兼容端点）
- Kubernetes 集群（可选 - 如果无法访问，工具将自动禁用）
### 安装
```bash
git clone https://github.com/codefuture-io/kube-agents.git
cd kube-agents
make build
```
### 运行
```bash
# 交互式聊天（自动加载 Kubernetes 工具）
./bin/kube-agents chat --api-key=sk-your-key
# 启动 HTTP + A2A 服务器
./bin/kube-agents serve --api-key=sk-your-key
# 使用配置文件
./bin/kube-agents serve --config=config/kube-agents.yaml --api-key=sk-your-key
```
### 环境变量
| 变量 | 是否必填 | 描述 |
|----------|----------|-------------|
| `DEEPSEEK_API_KEY` | 是 | DeepSeek API 密钥 |
| `OPENAI_API_KEY` | 否 | 备用 API 密钥 |
| `OPENAI_BASE_URL` | 否 | 自定义基准 URL（默认：`https://api.deepseek.com`） |
| `KUBECONFIG` | 否 | kubeconfig 路径（默认：`~/.kube/config`） |
---
## 命令行界面参考
### 命令
| 命令 | 描述 |
|---------|-------------|
| `kube-agents chat` | 与 Kubernetes 代理进行交互式终端聊天 |
| `kube-agents serve` | 启动 HTTP + gRPC + A2A 服务器 |
| `kube-agents version` | 以表格格式打印版本信息 |
### 标志
| 标志 | 默认值 | 环境变量备用 | 描述 |
|------|---------|-------------|-------------|
| `--api-key` | - | `DEEPSEEK_API_KEY`→`OPENAI_API_KEY` | API 密钥 |
| `--base-url` | - | `OPENAI_BASE_URL` | API 基准 URL |
| `--model` | `deepseek-chat` | - | 模型名称 |
| `--config` | `config/kube-agents.yaml` | - | 配置文件路径 |
| `--log-level` | `info` | - | `debug`、`info`、`warn`、`error` |
| `--log-format` | `text` | - | `text`、`json` |
| `--log-add-source` | `false` | - | 在日志中包含源文件:行号 |
| `--log-file-output` | `false` | - | 将日志写入文件而不是 stderr |
| `--log-file-path` | - | - | 日志文件路径 |
| `--log-max-size` | `100` | - | 旋转前的最大 MB 数 |
| `--log-max-backups` | `10` | - | 要保留的最大旧日志文件数 |
| `--log-max-age` | `30` | - | 要保留的旧日志的最大天数 |
### 日志记录
```bash
# JSON 格式，调试级别
./bin/kube-agents serve --log-format=json --log-level=debug
# 写入文件并旋转
./bin/kube-agents serve \
--log-file-output --log-file-path=/var/log/kube-agents.log \
--log-max-size=500 --log-max-backups=30
```
---
## HTTP API
### 端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/v1/chat/completions` | 聊天完成（非流式 + SSE 流式） |
| `POST` | `/v1/knowledge/upload` | 上传文件到 RAG 知识库 |
| `GET` | `/v1/knowledge/files` | 列出已上传的文件 |
| `GET` | `/v1/sessions` | 列出所有会话 |
| `DELETE` | `/v1/sessions/{id}` | 删除会话 |
### 会话管理
会话保留对话历史记录。通过传递其 ID 可以恢复任何会话。
```bash
# 列出会话
curl http://localhost:8080/v1/sessions
# 删除会话
curl -X DELETE http://localhost:8080/v1/sessions/my-session-id
```
CLI 聊天模式显示类似 Claude Code 的启动横幅并生成会话 ID：
```bash
$ ./bin/kube-agents chat --api-key=sk-xxx
╭─── kube-agents 0.1.0 ──────────────────────────────────────────────────────────────────────────────╮
│ │ │
│ 欢迎回来！ │ 开始使用提示 │
│ │ /help 显示可用命令 │
│ ▐⎈██⎈▜▌ │ /exit 退出并保存会话 │
│ ▝▜█████▛▘ │ ────────────────────────────────────────────────────────── │
│ ▘▘ ▝▝ │ 会话 │
│ │ 恢复： chat --session-id <id> │
│ │ 清除： chat --clear-session <id> │
│ │ │
│ 模型： deepseek-chat │ │
│ 命名空间： default │ │
│ 会话： 1d75ebe8...699488cbfda6 │ │
│ ~/github/kube-agents │ │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
> /exit
再见！要恢复：
kube-agents chat --api-key=... --session-id=1d75ebe8...
```
通过设置 `X-Session-ID` 头或 `--session-id` 标志恢复 HTTP 会话。
### 聊天完成
```bash
curl -X POST http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "列出所有命名空间"}],
"stream": false
}'
```
### 流式（SSE）
```bash
curl -N -X POST http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "获取 deployment nginx 详情"}],
"stream": true
}'
```
### 响应格式
```json
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"model": "gpt-3.5-turbo",
"choices": [{
"index": 0,
"message": {"role": "assistant", "content": "default 命名空间有 7 个 pod：\n..."},
"finish_reason": "stop"
}],
"usage": {"prompt_tokens": 3019, "completion_tokens": 47, "total_tokens": 3066}
}
```
---
### 知识上传
在运行时将文件上传到 RAG 知识库。接受的格式：`.md`、`.txt`、`.yaml`、`.yml`、`.json`、`.html`、`.pdf`（最大 10MB）。
文件按会话 ID 组织。如果配置了 S3，文件将存储在 `s3://{bucket}/{prefix}/{sessionID}/{filename}`。否则，它们将存储在本地的 `$TMPDIR/kube-agents-knowledge/{sessionID}/`。
```bash
# 基本上传
curl -X POST http://localhost:8080/v1/knowledge/upload \
-F "file=@docs/kubernetes-guide.md"
# 带有会话 ID（通过头部或查询参数）
curl -X POST http://localhost:8080/v1/knowledge/upload \
-H "X-Session-ID: user-001" \
-F "file=@docs/k8s-guide.md"
curl -X POST "http://localhost:8080/v1/knowledge/upload?session=user-001" \
-F "file=@docs/k8s-guide.md"
```
成功响应：
```json
{"message":"文件已上传并索引","filename":"k8s-guide.md","size":2048,"upload_dir":"/tmp/kube-agents-knowledge"}
```
列出已上传的文件：
```bash
curl http://localhost:8080/v1/knowledge/files
# {"upload_dir":"/tmp/kube-agents-knowledge","files":["k8s-guide.md","README.md"]}
```
> **注意**：内置文本搜索（不需要嵌入式 API）搜索配置的 `knowledge.sources` 目录中的 `.md/.txt/.yaml` 文件。上传的文件存储但仅在嵌入式 API 可用时才会被索引。
---
## A2A 协议
kube-agents 实现 [Agent-to-Agent](https://github.com/trpc-group/trpc-a2a-go) 协议。其他 AI 代理可以发现并调用 kube-agents 作为工具。
### 启用
```yaml
server:
a2a:
enabled: true
host: "kube-agents.default.svc.cluster.local:18080"
```
### 端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/.well-known/agent-card.json` | 代理元数据发现 |
| `POST` | `/` | JSON-RPC 2.0 端点 |
### 代理卡发现
```bash
curl http://localhost:18080/.well-known/agent-card.json
```
响应：
```json
{
"name": "kube-agents",
"description": "带有 27 个内置 Kubernetes 工具的 Kubernetes AI 运维助手",
"url": "http://localhost:18080"
}
```
### 非流式（`message/send`）
```bash
curl -X POST http://localhost:18080/ \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "这个集群有多少个命名空间？"}]
}
}
}'
```
响应：
```json
{
"jsonrpc": "2.0",
"result": {
"artifacts": [{
"parts": [{"kind": "text", "text": "这个集群有 30 个命名空间。"}]
}]
}
}
```
### 流式（`message/stream`）
```bash
curl -N -X POST http://localhost:18080/ \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"jsonrpc": "2.0",
"method": "message/stream",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "列出 default 命名空间中的所有 pod"}]
}
}
}'
```
---
## Kubernetes 工具
27 个内置工具 + `knowledge_search`（RAG），针对 Kubernetes v1.31.12 验证。
### 核心资源
| 工具 | 动词 | 返回 |
|------|------|---------|
| `pod_list` | list | 名称、状态、节点、IP、重启次数 |
| `pod_get` | get | 容器、条件、事件、标签 |
| `pod_logs` | get | 日志输出（可配置尾部 + 容器） |
| `pod_delete` | delete | 确认消息 |
| `deployment_list` | list | 就绪/可用副本 |
| `deployment_get` | get | 副本、镜像、策略、条件 |
| `deployment_scale` | update | 缩放副本 |
| `deployment_update` | update | 副本、镜像、节点选择器、容忍度 |
| `service_list` | list | 类型、集群 IP、端口 |
| `service_get` | get | 端口、选择器、外部 IP |
| `namespace_list` | list | 名称、状态、年龄 |
| `namespace_get` | get | 标签 |
| `namespace_set` | - | 切换活动命名空间 |
| `event_list` | list | 按类型过滤（正常/警告） |
| `node_list` | list | 状态、角色、版本、CPU、内存 |
| `node_get` | get | 容量、可分配、条件、污点、IP |
### 网络和自动扩缩
| 工具 | 动词 | 返回 |
|------|------|---------|
| `ingress_list` | list | 主机、Ingress 控制器 |
| `ingress_get` | get | TLS、路由规则、后端服务 |
| `hpa_list` | list | 缩放目标、最小/最大副本、当前 CPU% |
| `hpa_get` | get | 指标规格、当前负载、条件 |
### 配置和密钥
| 工具 | 动词 | 返回 |
|------|------|---------|
| `configmap_list` | list | 键计数 |
| `configmap_get` | get | 键、数据（>256 个字符截断）、二进制键 |
| `secret_list` | list | 类型、键计数（**值永不暴露**） |
| `secret_get` | get | 键名、类型、标签（**值永不暴露**） |
### 通用和元数据
| 工具 | 动词 | 返回 |
|------|------|---------|
| `resource_list` | list | 通过动态客户端的任意 Kubernetes/CRD 资源 |
| `resource_get` | get | 完整的非结构化对象 |
| `cluster_info` | get | 版本、API 组、节点/命名空间计数 |
---
## 技能
`skills/` 中的可重用工作流程模块（SKILL.md 格式）：
| 技能 | 目的 | 示例用法 |
|-------|---------|-------------|
| `k8s-diagnose` | CrashLoopBackOff、OOMKilled、调度失败 | "为什么我的 pod 崩溃了？" |
| `k8s-deploy` | 滚动更新、回滚、缩放、健康检查 | "将 nginx 缩放至 5 个副本" |
| `k8s-security` | RBAC 审计、特权容器、暴露的服务 | "查找特权 pod" |
---
## 插件
| 插件 | 钩子点 | 行为 |
|--------|-----------|----------|
| `audit` | `AfterTool` | 记录每次工具调用，带有时间戳/结果/错误 |
| `ratelimit` | `BeforeAgent` | 会话请求计数器（每会话 100 请求） |
| `logging` | `BeforeAgent`+`AfterAgent` | 代理生命周期事件 |
自定义插件示例：
```go
type MyPlugin struct{}
func (p *MyPlugin) Name() string { return "my-plugin" }
func (p *MyPlugin) Register(r *plugin.Registry) {
r.BeforeAgent(func(ctx context.Context, args *agent.BeforeAgentArgs) (*agent.BeforeAgentResult, error) {
slog.Info("custom logic before agent runs")
return &agent.BeforeAgentResult{Context: ctx}, nil
})
}
```
---
## 配置
完整参考 - `config/kube-agents.yaml`：
```yaml
server:
http:
enabled: true
port: 8080
grpc:
enabled: false
port: 9090
a2a:
enabled: false
host: "kube-agents.default.svc.cluster.local:18080"
model:
provider: deepseek
name: deepseek-chat
apiKeyEnv: DEEPSEEK_API_KEY
baseUrl: ""
auth:
mode: serviceaccount # serviceaccount | jwt
jwt:
issuer: kube-agents
secretEnv: JWT_SECRET
session:
backend: memory # memory | redis
redis:
addr: "redis:6379"
passwordEnv: REDIS_PASSWORD
db: 0
memory:
backend: memory
redis:
addr: "redis:6379"
passwordEnv: REDIS_PASSWORD
db: 1
knowledge:
sources:
- type: file
path: ./docs/k8s-reference/
- type: url
path: https://kubernetes.io/docs/
mcpServers:
- name: kubectl
transport: stdio
command: kubectl
args: ["mcp"]
plugins:
- audit
- ratelimit
- logging
skillsDir: ./skills/
```
---
## 架构
```
HTTP/gRPC/CLI/A2A
│
▼
┌──────────────────┐
│ 认证插件 │ ← TokenReview + SubjectAccessReview（Kubernetes 原生）
└──────┬───────────┘
│
▼
┌──────────────────┐
│ 运行器 │ ← 会话服务 + 内存服务 + 插件
└──────┬───────────┘
│
▼
┌──────────────────┐
│ Kubernetes LLMAgent │ ← 系统提示 + 24 个 Kubernetes 工具 + 技能 + 知识
└──────┬───────────┘
│
├──→ Kubernetes 工具 （client-go → Kubernetes API 服务器）
├──→ MCP 工具 （外部 stdio/SSE 服务器）
├──→ 技能 （k8s-diagnose / 部署 / 安全）
└──→ 知识 （RAG：对 Kubernetes 文档的语义搜索）
```
### 请求生命周期
1. 请求通过 **CLI** / **HTTP** / **A2A** 到达
2. **认证插件** 验证令牌（TokenReview）并将用户身份注入会话状态
3. **运行器** 创建/查找会话，附加内存上下文，应用插件
4. **LLMAgent** 接收带有系统提示 + 可用工具的消息
5. LLM 根据用户意图决定调用哪些工具
6. **工具** 通过 client-go 对 Kubernetes API 执行操作；审计插件记录调用
7. 响应通过 运行器 → 会话持久性 → 客户端流回
---
## 项目布局
```
kube-agents/
├── cmd/
│ ├── kube-agents/ # 主二进制文件
│ │ ├── main.go # 入口点
│ │ └── app/
│ │ ├── cmd.go # Cobra 命令（serve/chat/version）
│ │ └── options/options.go # CLI 标志 + 验证
│ └── k8s-verify/ # Kubernetes 工具验证实用程序
├── pkg/
│ ├── agent/ # 代理工厂 + 计算器工具
│ ├── auth/ # 认证插件（TokenReview + SubjectAccessReview）
│ ├── config/ # YAML 配置结构体 + 加载器
│ ├── k8s/
│ │ ├── client.go # client-go 工厂（集群内 + kubeconfig）
│ │ └── tools/ # 24 个 Kubernetes 函数工具（7 个文件）
│ ├── knowledge/ # RAG 知识存储
│ ├── mcp/ # MCP 工具注册表
│ ├── memory/ # 内存服务工厂
│ ├── plugin/ # 内置插件（audit/ratelimit/logging）
│ ├── server/ # HTTP + A2A 服务器设置
│ ├── session/ # 会话服务工厂
│ └── skill/ # 技能注册表（SKILL.md 加载器）
├── internal/event/ # 流事件处理器（推理缓冲区）
├── version/ # 版本信息（注入 ldflags）
├── utils/log/ # slog 初始化 + lumberjack 旋转
├── skills/ # SKILL.md 工作流程模块（3 个技能）
├── config/ # 默认配置文件
├── deployments/ # Kubernetes 清单（部署、服务、配置文件、RBAC）
├── build/ # 多阶段 Dockerfile
└── Makefile # 构建、测试、docker 目标
```
---
## 部署
### Docker
```bash
make docker-build IMG=your-registry/kube-agents:0.1.0
make docker-push IMG=your-registry/kube-agents:0.1.0
make docker-buildx IMG=your-registry/kube-agents:0.1.0 # 多架构
```
### Kubernetes
```bash
kubectl apply -f deployments/
```
创建：ServiceAccount → ClusterRole → ClusterRoleBinding → ConfigMap → Deployment → Service
### RBAC
| API 组 | 资源 | 动词 |
|-----------|-----------|-------|
| `""`（核心） | pods、pods/log、services、namespaces、events、nodes | get、list、watch |
| `""`（核心） | pods、services | create、update、delete |
| `apps` | deployments、deployments/scale、replicasets | get、list、watch、update |
| `authentication.k8s.io` | tokenreviews | create |
| `authorization.k8s.io` | subjectaccessreviews | create |
| `networking.k8s.io`、`batch`、`apiextensions.k8s.io` | `*` | get、list |
---
## 验证
独立实用程序测试所有工具对抗真实集群：
```bash
KUBECONFIG=$HOME/.kube/config go run ./cmd/k8s-verify/
```
输出：
```
集群连接（命名空间=default）
总工具数：24
PASS cluster_info （版本：v1.31.12）
PASS namespace_list （30 个项目）
PASS pod_list （7 个项目）
PASS deployment_list （4 个项目）
PASS service_list （4 个项目）
PASS ingress_list （2 个项目）
PASS configmap_list （6 个项目）
PASS secret_list （2 个项目）
PASS pod_get （名称：ba-0223-app-ccp-r5t67）
PASS deployment_get （名称：ba-0223-app-ccp）
PASS service_get （名称：dual-stack-svc）
PASS ingress_get （名称：dual-stack-ing）
...
结果：17 通过，0 失败
```
---
## 开发
```bash
make fmt # go fmt ./...
make vet # go vet ./...
make build # 构建二进制文件 → bin/kube-agents
make run # go run ./cmd/kube-agents/
make test # go test -race ./...
make test-cover # go test -cover -coverprofile=coverage.out ./...
```
## 许可证
Apache License 2.0
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器