README
¶
k8s-lookout
Data-plane intelligence for core-agent:
deterministic, token-dense eyes on Kubernetes/GKE clusters for LLM-driven
troubleshooting agents.
Two halves, one multicall binary (lookout):
- Read-path — one-shot diagnostic commands an agent runs mid-investigation
(
lookout triage|state|stab|perf|cloud|bundle|health), emitting compressed, secret-safe, logfmt/JSON findings instead of raw telemetry dumps. - Watch-path —
lookout watch, a resident per-cluster sentinel that turns leading indicators (state transitions, trend slopes, expiry countdowns) into per-incident agent sessions with warm context — detecting issues before, or as, they happen rather than after.
Status: M1 complete. The read-path core has shipped: lookout triage delta|logs|spec, state edges, bundle, health, the §4.2 output
envelope with the §6.5 sanitizer on every surface, the pkg/graph topology
index, lookout mcp (every check as an MCP tool), and the first workflow
skills (skills/ — k8s-triage, cluster-health, and the
per-symptom playbooks). An incident session can be investigated with lookout
tools alone, and lookout health answers "any issues in this cluster?" in
one call — see docs/milestones/M1.md for the
exit-check evidence (M0: lookout watch, the
moved k8s-event-watcher, image-swap compatible). Images are published at
ghcr.io/go-steer/lookout. The complete specification is
docs/DESIGN.md; next up is the closed loop (M2, §14):
recovery injects, storm correlation, severity routing, and enrichment.
Roughly 80% of the suite is pure client-go and runs on any conformant
Kubernetes cluster; GKE/GCP-specific capability lives behind a cloud-provider
boundary (DESIGN.md §2).
Ecosystem
| Repo | Role |
|---|---|
core-agent |
the agent daemon; lookout talks to it over POST /sessions + /inject |
ax |
fleet layer; consumes lookout's rollup-ready signal schema across clusters |
License
Apache 2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
lookout
command
Command lookout is the single multicall binary of k8s-lookout (DESIGN.md §4.1): deterministic, token-dense reads of Kubernetes/GKE clusters for agent-driven troubleshooting, plus the resident per-cluster sentinel, `lookout watch`.
|
Command lookout is the single multicall binary of k8s-lookout (DESIGN.md §4.1): deterministic, token-dense reads of Kubernetes/GKE clusters for agent-driven troubleshooting, plus the resident per-cluster sentinel, `lookout watch`. |
|
internal
|
|
|
mcpserver
Package mcpserver serves the registered read-path checks as MCP tools (DESIGN.md §4.3): every non-hidden checks.Command becomes one tool whose name is the command's MCPName, whose description is the command's §4.4.1 micro-skill metadata, and whose input schema is derived mechanically from the same FlagSpecs that generate --help.
|
Package mcpserver serves the registered read-path checks as MCP tools (DESIGN.md §4.3): every non-hidden checks.Command becomes one tool whose name is the command's MCPName, whose description is the command's §4.4.1 micro-skill metadata, and whose input schema is derived mechanically from the same FlagSpecs that generate --help. |
|
skilldoc
Package skilldoc generates the per-command reference stubs under skills/<skill>/references/ from the pkg/checks command metadata — the third generated surface after --help and the MCP schemas (DESIGN.md §4.4.3: one source of truth, generated outward).
|
Package skilldoc generates the per-command reference stubs under skills/<skill>/references/ from the pkg/checks command metadata — the third generated surface after --help and the MCP schemas (DESIGN.md §4.4.3: one source of truth, generated outward). |
|
skilldoc/gen
command
Command gen regenerates the skill reference stubs under skills/*/references/ from the pkg/checks registry.
|
Command gen regenerates the skill reference stubs under skills/*/references/ from the pkg/checks registry. |
|
watch
Command k8s-event-watcher is the v2.6 semi-autonomous-triage sidecar.
|
Command k8s-event-watcher is the v2.6 semi-autonomous-triage sidecar. |
|
pkg
|
|
|
checks
Package checks is the read-path command surface: implementations plus the metadata registry that is the single source of truth for every invocation surface (§4.3, §4.4.3).
|
Package checks is the read-path command surface: implementations plus the metadata registry that is the single source of truth for every invocation surface (§4.3, §4.4.3). |
|
checks/bundle
Package bundle implements `lookout bundle` (DESIGN.md §5): the first tool call of every incident.
|
Package bundle implements `lookout bundle` (DESIGN.md §5): the first tool call of every incident. |
|
checks/checktest
Package checktest is the §13 contract-test scaffold for read-path commands.
|
Package checktest is the §13 contract-test scaffold for read-path commands. |
|
checks/delta
Package delta implements `lookout triage delta` (DESIGN.md §5): one scan of the cluster's current state that reports every abnormal object and nothing else.
|
Package delta implements `lookout triage delta` (DESIGN.md §5): one scan of the cluster's current state that reports every abnormal object and nothing else. |
|
checks/health
Package health implements `lookout health` (DESIGN.md §5): the "are there issues with this cluster?" scorecard.
|
Package health implements `lookout health` (DESIGN.md §5): the "are there issues with this cluster?" scorecard. |
|
checks/logs
Package logs implements `lookout triage logs` (DESIGN.md §5): the token-density workhorse of the read path.
|
Package logs implements `lookout triage logs` (DESIGN.md §5): the token-density workhorse of the read path. |
|
checks/state
Package state implements the `lookout state` command group (DESIGN.md §5): dependency and configuration verification.
|
Package state implements the `lookout state` command group (DESIGN.md §5): dependency and configuration verification. |
|
cloud
Package cloud is the provider boundary of DESIGN.md §2: everything cloud-touching in lookout (capacity explanations, quota inventory, orphan sweeps, metrics queries, IP-space utilization, stockout extraction, workload-identity verification) goes through the Provider interface defined here.
|
Package cloud is the provider boundary of DESIGN.md §2: everything cloud-touching in lookout (capacity explanations, quota inventory, orphan sweeps, metrics queries, IP-space utilization, stockout extraction, workload-identity verification) goes through the Provider interface defined here. |
|
emit
Package emit implements the §4.2 output contract shared by every read-path command: findings on stdout as flat, ordered key=value records (logfmt by default, one JSON object per line with --format=json), a mandatory terminating summary line (`scanned=<n> findings=<n> elapsed=<d>`), diagnostics on stderr only, and exit codes 0 data / 1 runtime / 2 usage.
|
Package emit implements the §4.2 output contract shared by every read-path command: findings on stdout as flat, ordered key=value records (logfmt by default, one JSON object per line with --format=json), a mandatory terminating summary line (`scanned=<n> findings=<n> elapsed=<d>`), diagnostics on stderr only, and exit codes 0 data / 1 runtime / 2 usage. |
|
engine
Package engine implements the watch-path signal pipeline: the Event.Reason / namespace filter and the rolling-window dedup cache that decide which observed Kubernetes events become incidents.
|
Package engine implements the watch-path signal pipeline: the Event.Reason / namespace filter and the rolling-window dedup cache that decide which observed Kubernetes events become incidents. |
|
graph
Package graph is the in-memory topology index of DESIGN.md §6: a directed, typed graph centered on the Pod, connecting the traffic/policy layers above it (Ingress → Service/EndpointSlice → NetworkPolicy → Pod) to the infrastructure below (Containers, ConfigMaps/Secrets, PVCs, Node, Zone).
|
Package graph is the in-memory topology index of DESIGN.md §6: a directed, typed graph centered on the Pod, connecting the traffic/policy layers above it (Ingress → Service/EndpointSlice → NetworkPolicy → Pod) to the infrastructure below (Containers, ConfigMaps/Secrets, PVCs, Node, Zone). |
|
inject
Package inject implements the thin HTTP client the watch sentinel uses to speak to a core-agent daemon, plus the frozen wire types it POSTs (see payload.go).
|
Package inject implements the thin HTTP client the watch sentinel uses to speak to a core-agent daemon, plus the frozen wire types it POSTs (see payload.go). |
|
kube
Package kube provides Kubernetes client bootstrap shared by the lookout subcommands.
|
Package kube provides Kubernetes client bootstrap shared by the lookout subcommands. |
Click to show internal directories.
Click to hide internal directories.