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: M2 complete. The closed loop has shipped on top of the M1
read-path core: lookout watch is now the §7.1 signal engine — pluggable
sources (k8s-events plus the leading-indicator object-state source),
storm correlation via graph blast-radius keys (--storm: a node failure
opens ONE kind=storm session, not one per evicted pod), recovery injects
(kind=resolved outcome records into the incident's own session when the
symptom verifiably clears — fix-verify without agent polling), severity
routing with the shared watchboard digest for warning-class noise, and
§7.6 enrichment (the in-process bundle attached to critical sessions, so
they start warm). Measured in the exit drill: 33 affected objects → 3
sessions (1 storm); fix → resolved in 76 s with zero polling — see
docs/milestones/M2.md for the evidence
(M1: read-path core;
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 are the leading-indicator
sources and history (M3, §14): rollout, saturation, degradation,
expiry, the raw store with graph snapshots, and the --at time-travel
queries.
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 (DESIGN.md §7): the Signal type carried between stages (§8 schema), the frozen cross-cluster Fingerprint, and the reason/namespace filter and rolling-window dedup cache that decide which observed signals become incidents.
|
Package engine implements the watch-path signal pipeline (DESIGN.md §7): the Signal type carried between stages (§8 schema), the frozen cross-cluster Fingerprint, and the reason/namespace filter and rolling-window dedup cache that decide which observed signals 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. |
|
sources
Package sources defines the signal-source contract of the sentinel (DESIGN.md §7.2): pluggable sources feeding one shared pipeline — one resident process per cluster, never N sidecars.
|
Package sources defines the signal-source contract of the sentinel (DESIGN.md §7.2): pluggable sources feeding one shared pipeline — one resident process per cluster, never N sidecars. |
|
sources/k8sevents
Package k8sevents is the first signal source (DESIGN.md §7.2): the core/v1 Event informer that was internal/watch's watcher — the M0 k8s-event-watcher — refactored behind the pkg/sources.Source interface with semantics unchanged.
|
Package k8sevents is the first signal source (DESIGN.md §7.2): the core/v1 Event informer that was internal/watch's watcher — the M0 k8s-event-watcher — refactored behind the pkg/sources.Source interface with semantics unchanged. |
|
sources/objectstate
Package objectstate is the object-state signal source (DESIGN.md §7.2 row 2): leading indicators from STATE TRANSITIONS, observed by shared informers on Pods, Nodes, Deployments, EndpointSlices, and PodDisruptionBudgets.
|
Package objectstate is the object-state signal source (DESIGN.md §7.2 row 2): leading indicators from STATE TRANSITIONS, observed by shared informers on Pods, Nodes, Deployments, EndpointSlices, and PodDisruptionBudgets. |
Click to show internal directories.
Click to hide internal directories.