approvefor/k8s-incident-copilot

# Kubernetes 事故 AI SRE Copilot [](https://github.com/approvefor/k8s-incident-copilot/actions/workflows/ci.yml)    **Kubernetes | Helm | FastAPI | Qdrant | OpenTelemetry | Policy-as-Code | 人工审批 | Postgres 审计 | AI Evals** 生产级 DevOps 宠物项目，展示了 DevOps/SRE 工程师如何在事故处理工作流中安全地使用 AI。 这不是一个简单的聊天机器人套壳。它是一个 AI 辅助的 SRE 平台，能够关联日志、运维手册 (runbook)、Kubernetes 上下文、指标式信号、策略护栏、审批、审计跟踪、CI/CD、Helm 以及可观测性。 ## 目录 - [概述](#overview) - [功能说明](#what-it-does) - [展示的技能](#skills-demonstrated) - [架构](#architecture) - [本地演示](#local-demo) - [演示输出](#demo-output) - [安全护栏](#guardrails) - [Evals](#evals) - [生产环境清单](#production-checklist) - [仓库结构](#repository-layout) - [面试定位](#interview-positioning) ## 概述 该演示展示了一个 AI Copilot 如何诊断 Kubernetes 风格的事故、引用运维手册、提出修复建议、在访问 secret 时被拦截，并将所有操作记录到审计跟踪中。 ## 功能说明 核心工作流： 1. 一个 worker 生成操作日志。 2. API 将日志索引到 Qdrant 中以便搜索。 3. 将运维手册作为轻量级的 RAG 上下文进行搜索。 4. `POST /incidents/analyze` 生成一份 AI SRE 分诊报告，包含执行摘要、置信度、时间线、证据、运维手册引用和修复计划。 5. `POST /actions/plan` 根据策略评估建议的操作。 6. `POST /actions/execute` 仅返回 dry-run 命令；真正的执行应属于受限的 action-runner。 7. `GET /audit/events` 展示了 AI 看到了什么、提出了什么，以及运维人员批准或拒绝了什么。 ## 展示的技能 - AI 事故分诊，而非通用聊天 - 基于操作运维手册的 RAG - 用于演示的本地确定性 embeddings，以及用于真实语义检索的 OpenAI embeddings - 针对 AI 生成操作的 policy-as-code - 人工介入审批 (Human-in-the-loop approvals) - 具有本地回退机制的持久化 Postgres 审计跟踪 - 通过 Helm 进行 Kubernetes 部署 - health/readiness 检查、resources、HPA、PDB、NetworkPolicy - 非根容器和受限的安全上下文 - Prometheus 指标、Grafana dashboard、兼容 Loki/Jaeger 的可观测性 - GitHub Actions 构建、测试、扫描、SBOM、Cosign 签名、镜像推送、Helm 验证和部署 - 用于运行时和供应链加固的 Kyverno 准入控制策略示例 - 针对 AI 安全和质量预期的 evals 测试用例 ## 架构 详细的权衡和设计原理记录在 [ARCHITECTURE.md](ARCHITECTURE.md) 中。 ``` flowchart LR Operator[SRE / DevOps Engineer] --> API[FastAPI SRE Copilot API] Worker[Log Worker] --> API API --> Qdrant[(Qdrant Vector Search)] API --> Runbooks[Markdown Runbooks] API --> AI[AI Provider Layer] AI --> Report[Incident Triage Report] Report --> Policy[Policy Engine] Policy --> Approval[Human Approval] Approval --> DryRun[Dry-run Action Command] API --> Audit[(Postgres Audit Trail)] API --> Prom[Prometheus Metrics] API --> Jaeger[Jaeger Traces] Prom --> Grafana[Grafana Dashboard] ``` ## 本地演示 WSL 前置条件： ``` sudo apt update sudo apt install -y python3 python3-pip python3-venv make curl ``` Python 环境： ``` make setup ``` 如果 Ubuntu 提示 `ensurepip` 不可用，请安装它建议的带版本号的 venv 包，例如： ``` sudo apt install -y python3.12-venv make setup ``` Docker 选项： - Docker Desktop：为你的 Ubuntu 发行版启用 WSL 集成。 - WSL 原生 Docker：安装 Docker Engine 和 Compose 插件。 - 旧版环境：演示脚本和 Makefile 也支持 `docker-compose`。 完整验证需要 Helm： ``` curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash ``` 请勿运行 `sudo make verify`；这可能会隐藏你的用户级 Python/Docker 配置，并创建属于 root 用户的文件。 一键演示： ``` .\scripts\demo.ps1 ``` 或者： ``` ./scripts/demo.sh ``` 如果在面试中不想实际运行技术栈，请参阅适合面试演示的无运行流程说明 [docs/demo-transcript.md](docs/demo-transcript.md)。 技术栈运行后的冒烟测试： ``` make smoke ``` 预期的冒烟测试输出记录在 [docs/demo-output.md](docs/demo-output.md) 中。 ## 演示输出  面试路径： ``` make test make evals make compose-up make smoke ./scripts/demo.sh ``` 手动启动： ``` cp .env.example .env make compose-up ``` 如果本地 Qdrant/Postgres 演示数据在多次运行之间变得陈旧或损坏： ``` make compose-reset make compose-up make smoke ``` WSL/Unix 快捷方式： ``` make test make evals make helm-lint make helm-template make demo make compose-logs ``` 访问地址： - API 文档：http://localhost:8000/docs - 指标：http://localhost:8000/metrics - Qdrant：http://localhost:6333/dashboard - MinIO：http://localhost:9001 ## 安全护栏 策略位于 `policy/actions.yaml` 中。 允许的示例： - `rollout_status` - `scale_deployment` - `rollback_deployment` - `restart_deployment` 拒绝的示例： - `get_secret` - `delete_secret` - `delete_namespace` - `exec_shell` - `apply_raw_manifest` - `delete_persistent_volume` 更改状态的操作需要 `approved: true`，但该 API 被特意设计为仅限 dry-run。生产环境部署应将实际执行委托给具有作用域受限的 Kubernetes RBAC 的独立受限 action-runner。 准入控制示例位于 [deploy/security/kyverno-policies.yaml](deploy/security/kyverno-policies.yaml)。 ## Embeddings 默认可复现提供商： ``` EMBEDDING_PROVIDER=local_hash ``` 生产环境语义提供商： ``` EMBEDDING_PROVIDER=openai OPENAI_API_KEY=... OPENAI_EMBEDDING_MODEL=text-embedding-3-small EMBEDDING_DIMENSIONS=1536 ``` 在 Kubernetes 中，使用以下命令启用 OpenAI embeddings： ``` helm upgrade --install ai-platform deploy/helm/ai-platform \ --namespace ai-platform \ --set api.openai.enabled=true \ --set networkPolicy.allowExternalHttps=true ``` 默认情况下，`OPENAI_API_KEY` 会从 `ai-platform-secrets` 中读取。 更改 embedding 维度需要创建全新的 Qdrant collection 或使用新的 `QDRANT_COLLECTION` 名称。如果现有 collection 维度与当前激活的 embedding 提供商不匹配，readiness 探针将会失败。 ## 持久化 当配置了 `DATABASE_URL` 时，审计事件将被持久化到 Postgres 中。Helm chart 为捆绑的 PostgreSQL 依赖项模板化了一个默认 URL。对于外部数据库，请将 `api.audit.existingSecret` 设置为包含 `database-url` 的 secret。如果配置了 `DATABASE_URL` 但不可用，`/readyz` 将会失败，这样 Kubernetes 就不会将流量路由到没有持久化审计的 pod。 ## 事故时间线 每份分诊报告都包含一个简明的时间线： ``` T-10m deploy context collected T-05m latency and error-rate impact detected T-03m matching incident logs found T-01m relevant runbook cited T+00m AI remediation plan evaluated by policy ``` ## Kubernetes 演示 ``` helm dependency update deploy/helm/ai-platform helm upgrade --install ai-platform deploy/helm/ai-platform \ --namespace ai-platform \ --create-namespace ``` 该 chart 包含 readiness/liveness 探针、HPA、PDB、NetworkPolicy、ServiceAccount、非根安全上下文、可选的带 TLS 注释的 Ingress、Prometheus 抓取注解以及 OpenTelemetry exporter 配置。 Qdrant 服务 URL 默认根据 Helm release 名称生成。对于外部的 Qdrant 集群，请使用 `api.qdrantUrlOverride`。 默认的 Helm 值是自包含的，适用于作品集演示。生产环境的值会将外部数据库/OpenAI/MinIO 凭证移动到 `ai-platform-secrets` 中。 生产级配置值： ``` helm upgrade --install ai-platform deploy/helm/ai-platform \ --namespace ai-platform \ --create-namespace \ -f deploy/helm/ai-platform/values-production.yaml ``` 生产环境的值使用 SHA 风格的镜像标签占位符，并通过 `api.image.digest` 和 `worker.image.digest` 支持基于摘要锁定的不可变镜像。 ## Evals AI 行为预期定义在 `evals/incidents.yaml` 中。 使用以下命令运行： ``` python3 scripts/run-evals.py ``` ## 架构决策 - [ADR-001：AI 必须受策略约束](docs/adr/ADR-001-policy-constrained-ai.md) - [ADR-002：状态变更操作必须经过人工审批](docs/adr/ADR-002-human-approval-for-state-change.md) - [ADR-003：将运维手册作为引用来源](docs/adr/ADR-003-runbooks-as-citations.md) - [ADR-004：通过 Evals 保障 AI 安全](docs/adr/ADR-004-evals-for-ai-safety.md) ## 生产环境清单 请参阅 [docs/production-checklist.md](docs/production-checklist.md)。 ## 可观测性 将 `deploy/observability/grafana-dashboard.json` 导入到 Grafana 中，以展示请求率、p95 延迟、服务错误、pod 重启次数以及最近的 Loki 错误日志。 当设置了 `OTEL_EXPORTER_OTLP_ENDPOINT` 时，API 会导出 OpenTelemetry 跟踪数据。 ## 仓库结构 ``` api/ SRE Copilot API, policy, audit, AI provider, runbook search runbooks/ operational markdown runbooks for RAG policy/ allow/deny policy for AI-generated actions evals/ AI safety and quality eval scenarios worker/ synthetic log producer deploy/helm/ai-platform/ Kubernetes Helm chart deploy/observability/ Grafana/Prometheus/Loki/Jaeger assets deploy/security/ Vault/External Secrets/security docs terraform/aws/ example AWS infrastructure layer ansible/ k3s bootstrap automation tests/ API, runbook, and policy tests ``` ## 面试定位

标签：AIOps, DevSecOps, RAG, SRE, 上游代理, 偏差过滤, 子域名突变, 用户代理, 自动化运维, 自定义请求头, 请求拦截, 逆向工具