go-steer/k8s-lookout

# k8s-lookout 面向 Kubernetes/GKE 集群的确定性、高 token 密度监控工具，专为 LLM 驱动的故障排除代理设计 —— 它是 [`core-agent`](https://github.com/go-steer/core-agent) 的数据面配套工具。 一个包含多种调用的单一二进制文件 `lookout`，分为两部分： - **读取路径 (Read-path)** — 代理在调查中途运行的一次性诊断命令 （`bundle`, `health`, `triage …`, `state …`, …）。 每个命令都会输出经过压缩且防止机密泄露的 logfmt/JSON 分析结果，而不是原始的 遥测数据转储，并且始终以明确的摘要行结尾，因此 “集群健康” 绝不会变成模棱两可的沉默。 - **监控路径 (Watch-path)** — `lookout watch`，一个驻留在每个集群中的哨兵，它将 领先指标（状态转换、趋势斜率、到期倒计时）转化为带有预热上下文的逐事件代理会话 —— 在问题发生之前或发生之时将其捕获，而不是在发生之后。 这并非预测性/ML：每一个领先指标都是确定性的算术运算。 完整的规范详见 [`docs/DESIGN.md`](./docs/DESIGN.md)；有关 代码树中各文件的位置，请参阅 [仓库架构图](./docs/repo-map.md)。 [](https://github.com/go-steer/k8s-lookout/actions/workflows/ci.yml) [](./LICENSE) ## 安装说明 **容器镜像** (多架构 amd64 + arm64；distroless static； Sigstore 签名)： ``` docker pull ghcr.io/go-steer/lookout:latest # default: GCP-free, runs on any conformant cluster docker pull ghcr.io/go-steer/lookout:latest-gke # same binary + GKE/GCP provider (-tags allproviders) ``` 镜像的 `ENTRYPOINT` 是 `lookout watch`，可以直接替换 兼容 `ghcr.io/go-steer/k8s-event-watcher` 的部署。 使用以下命令验证签名： ``` cosign verify ghcr.io/go-steer/lookout:vX.Y.Z \ --certificate-identity-regexp '^https://github.com/go-steer/k8s-lookout' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com ``` **从源码构建** (Go 1.26+)： ``` go install github.com/go-steer/k8s-lookout/cmd/lookout@latest ``` ## 快速入门 — 读取路径 每一个读取命令都会针对你当前的 kubeconfig context 运行，无需 额外部署。只需一次调用即可解答“这个集群有问题吗？”： ``` lookout health ``` ``` kind=health.category severity=info reason=Unavailable message="requires cloud provider metrics (M4); no cloud provider configured" category=control-plane status=unavailable kind=health.category severity=info category=nodes status=healthy kind=health.category severity=warning category=crashloops status=degraded total=8 top="pod.restarts agent-sandbox-system/agent-sandbox-controller-7c69875fcc-n7xms; pod.restarts kube-system/coredns-7d764666f9-g82j9; …" kind=health.category severity=info category=pending status=healthy kind=health.category severity=info category=rollouts status=healthy … kind=pod.restarts severity=warning namespace=kube-system kind_of_object=Pod name=coredns-7d764666f9-g82j9 reason=ExcessiveRestarts fingerprint=sha256:e094a6ee… category=crashloops container=coredns restarts=62 scanned=16 findings=18 elapsed=537ms ``` （针对 kind 集群的真实输出，已缩减。）健康的资源会被 省略；但分类仍会明确给出结果。`lookout bundle --workload=Deployment/prod/api` 是事件发生时的首次调用：它提供 一个关联的快照，而不是 4-5 个独立的读取结果。退出码 0 表示 stdout 上只有 纯粹的 payload；诊断信息仅输出到 stderr。 ## 快速入门 — 哨兵 监控路径通过 [`deploy/`](./deploy/) 在每个集群中进行部署： ``` kubectl apply -f deploy/ ``` 这为哨兵提供了一个专用的 ServiceAccount，以及 最小必要权限的**只读** ClusterRole（它只进行观察；所有 变更操作都通过 core-agent 守护进程自身的权限控制门来执行）。 在 `deploy/51-deployment-watcher.yaml` 中将 `--daemon-url` 指向你的 core-agent 守护进程。DESIGN.md §11 中涵盖了命名空间范围（仅限 Role）和 项目层级（配额来源，`-gke` 镜像）的部署 —— 其 RBAC 范围 未得到满足的信号源在启动时会明确报错， 而绝不会表现为静默的空监控。 想先看看这两部分在真实故障下的表现吗？ [`examples/`](./examples/) 建立了一个 kind 集群，将哨兵 连接到一个捕获存根，并提供了演示工作负载和十种注入/验证/还原的 故障场景（`examples/e2e` 运行所有场景） —— 此外还包含了通过 skills 或 MCP 在 代理测试框架中测试 CLI 的配方。 ## 命令界面 | 命令 | 功能描述 | | --- | --- | | `watch` | 驻留哨兵：九种信号源 → 过滤 → 去重 → 风暴关联 → 严重性路由 → 丰富上下文 → 会话注入 | | `mcp` | 将每个读取命令 1:1 作为 MCP 工具提供服务（stdio 或 localhost HTTP） —— 这是 distroless 守护进程调用 lookout 的方式 | | `bundle` | 每次事件的首个调用：脱敏的 spec + 异常对象 + 断裂的边 + 影响范围 + 提炼后的日志，打包为一个 payload | | `health` | 十个类别的集群记分卡，与开放的哨兵分析结果和 triage 状态记录合并 | | `triage delta` | 一次扫描找出所有异常：故障工作负载、长期挂起的 Pending、节点压力、死锁的 PDB、降级的 add-ons、触及上限的配额 | | `triage logs` | 基于模板指纹的日志去重：将约 150k token 的日志压缩至约 350 | | `triage events` | 跨越 owner-reference 树的去重按时间排序的事件时间线 | | `triage top` | 当前时刻 CPU/mem 饱和度与限制的对比 | | `triage radius` | 根据拓扑索引得出工作负载的影响范围；`--at` 用于解答“在事件发生时”的情况 | | `triage changes` | “发生前有什么变化”：rollout、配置更新、扩缩容，范围限制在图邻域内 | | `triage spec` | 专为代理设计的 kubectl describe：经过脱敏、高 token 密度，可通过 `--diff` 与图历史进行对比 | | `triage status` | 读写 §9.4 中的 triage-status 记录，以便后续扫描报告的是经过诊断的实际情况，而不是全新的未知状态 | | `state edges` | 依赖图验证：config/secret 密钥、selector、endpoint、TLS 过期情况 | | `state webhooks` | 因后端失效而处于失败关闭状态的 admission webhooks | | `state wi` † | GKE Workload Identity KSA↔GSA 绑定验证 | | `state volumes` | RWO 多重挂载 / 跨可用区 PV 锁 | | `stab drift` | 通过 managedFields 检测 GitOps 管理器之外的配置漂移 | | `stab drain` | 所有会阻碍节点排空的因素 | | `perf probe` † | 控制面指标包：`apiserver`、`apf`、`etcd`、`startup` | | `cloud stockout\|orphans\|ipspace\|quota` † | GCP 侧读取：可用区资源耗尽、孤立的磁盘/LB、CIDR 利用率、配额余量 | | `net probe` | 从集群内部发起的主动 DNS/TCP/HTTP 检查 | † 需要 cloud provider（`-gke` 镜像 / `-tags gke` 构建）。套件中约 80% 是纯 client-go，可在任何兼容集群上运行； 默认构建不链接任何 GCP SDK。受限于 provider 的命令在原始集群上绝不会 崩溃或撒谎 —— 它们会输出一条明确的分析结果并以 exit 0 退出： ``` kind=cloud.unavailable severity=info reason=CapabilityUnavailable message="cloud quota needs the provider quota capability: no cloud provider configured" capability=quota provider=none scanned=0 findings=1 elapsed=0s unavailable="no cloud provider configured" ``` 代理教育内容位于 [`skills/`](./skills/README.md)：`k8s-triage`、 `cluster-health`、`gitops-drift`，以及针对特定症状的 `playbooks/` —— 这些 skills 教授跨命令的决策树，并安装到使用方 部署的 `.agents/skills/` 中。 ## 生态系统 | 仓库 | 角色 | | --- | --- | | [`core-agent`](https://github.com/go-steer/core-agent) | 代理守护进程；lookout 通过 `POST /sessions` + `/inject` 与其通信 | ## 文档 - [`docs/DESIGN.md`](./docs/DESIGN.md) — 完整的规范性说明文档 - [`docs/repo-map.md`](./docs/repo-map.md) — 仓库架构图：布局、数据路径、固定契约 - [`docs/signal-schema-v1.md`](./docs/signal-schema-v1.md) — 固定的舰队汇总网络传输契约 - [`docs/milestones/`](./docs/milestones/) — 各里程碑的退出验证（M0–M5 已完成，v0.6.0） - [`CHANGELOG.md`](./CHANGELOG.md) ## 许可证 Apache 2.0 — 详见 [LICENSE](./LICENSE)。

标签：API集成, EVTX分析, LLM集成, 可观测性, 故障排查, 日志审计, 请求拦截, 运维监控