How woonyong-choi/k8s-clue works
K8s Clue is a Kubernetes incident-diagnosis system: a read-only cluster agent gathers evidence, RCA workers identify causes and prepare bounded recovery proposals, and GitOps workers can offer those proposals as GitHub Draft PRs for human review. After a signed merge webhook, feedback workers verify recovery against later evidence. An event-driven runtime coordinates the services, while domain repositories persist incidents, evidence, inventory, and related state. The README documents an operational data catalog and user-facing incident views too; some links below reflect that documentation rather than sampled implementation calls.
Main entry points: rca-worker/app.py RCA worker · rca-feedback-worker/app.py Recovery verification · safe-pr-worker/app.py Safe PR worker · worker.py Worker runtime
Components 24
Evidence collection
- Cluster agent
src/services/target/cluster-agent/agent.py - API gateway
src/services/gateway/api-gateway/app.py - Evidence worker
src/services/ai/evidence-worker/app.py
RCA and recovery
- Incident worker
src/services/ai/incident-worker/app.py - RCA worker
src/services/ai/rca-worker/app.py - Cause rules
src/services/ai/agent/causes/engine.py - Recovery planning
src/services/ai/agent/recovery/engine.py - Recovery verification
src/services/ai/rca-feedback-worker/app.py
GitOps proposals
- Safe PR worker
src/services/gitops/safe-pr-worker/app.py - Manifest patching
src/domains/gitops/source_patch.py - SCM worker
src/services/gitops/scm-worker/app.py
Runtime and data
- PostgreSQL
- Event bus
src/packages/events/bus.py - Worker runtime
src/packages/runtime/worker.py - Controller runtime
src/packages/runtime/controller.py - Domain storage
src/packages/storage/engine.py
Catalog and views
- Inventory domain
src/domains/inventory/repository.py - Data catalog
src/domains/datacatalog/pipeline.py - Catalog API
src/domains/datacatalog/router.py - Incident UI
frontend/src/pages/IncidentsPage.tsx - RCA query API
src/domains/rca/query_router.py
Other components
- Kubernetes API
- GitHub App
- Human reviewer
Connections 24
- Kubernetes API → Cluster agent: read evidence
README.md - Cluster agent → API gateway: send bundle
README.md - API gateway → PostgreSQL: persist evidence
README.md - PostgreSQL → RCA worker: deliver events
README.md - Evidence worker → Event bus: publish events
src/services/ai/evidence-worker/app.py - Incident worker → Event bus: publish events
- RCA worker → Cause rules: evaluate causes
src/services/ai/agent/causes/engine.py - Cause rules → Recovery planning: plan recovery
- RCA worker → Safe PR worker: send cause proposal
README.md - Safe PR worker → Manifest patching: build patch
- Safe PR worker → SCM worker: send patch proposal
README.md - SCM worker → GitHub App: create draft PR
README.md - GitHub App → Human reviewer: request review
README.md - Human reviewer → GitHub App: merge decision
README.md - GitHub App → Recovery verification: send merge webhook
README.md - Recovery verification → PostgreSQL: record verification
README.md - Recovery verification → Cluster agent: compare new evidence
- Controller runtime → Worker runtime: starts services
src/packages/runtime/controller.py - Worker runtime → Event bus: consumes events
src/packages/runtime/worker.py - Worker runtime → Domain storage: records processing
src/packages/runtime/worker.py - Domain storage → PostgreSQL: uses database
- Inventory domain → Domain storage: uses database
src/domains/inventory/repository.py - Data catalog → Catalog API: serves catalog
- Incident UI → RCA query API: loads incident data