kubernetes-ontology

What it does

Kubernetes troubleshooting, shaped as a graph instead of a pile of object dumps.

The daemon builds an in-memory ontology from Kubernetes resources, keeps it fresh, and exposes stable CLI and HTTP queries for humans, tools, and agents.

Recover topology

Connect Pods, workloads, Services, Nodes, storage, images, RBAC, Events, webhooks, Helm releases, and charts.

Diagnose by entrypoint

Ask for a Pod or Workload and get a bounded evidence graph with warnings, budgets, conflicts, and ranked evidence.

Serve stable queries

Resolve entities, list relations, expand neighbors, and fetch diagnostic slices through CLI or HTTP APIs.

Inspect visually

Use the topology viewer to filter, expand, collapse, inspect provenance, and export the visible graph as JSON.

Why it is different

It gives agents and operators the same evidence surface.

Every conclusion stays tied to returned graph facts. That makes the output easier to inspect, easier to bound, and safer to hand to downstream automation.

Read-only by design

No mutation of observed workloads, no controller install requirement, and no external graph database dependency.
Fresh runtime graph

Bootstrap from the Kubernetes API, then refresh with informers and polling fallback.
Diagnostic boundaries

Partial results, traversal budgets, degraded sources, and conflicts travel with the response.
Agent-ready contract

Stable diagnostic semantics let AI agents reason from evidence without crawling the cluster from scratch.

What it sees

One graph for the relationships that matter during an incident.

Pods Workloads Services Nodes Secrets ConfigMaps ServiceAccounts RBAC PVCs PVs StorageClasses CSI drivers Images Events Admission webhooks Helm provenance

Start fast

Run it as a local diagnostic companion or install it in-cluster with Helm.

The open-source MVP stays lightweight: release binaries, a Helm chart, a CLI, a daemon, and a local topology viewer.

Install with Helm In-cluster daemon

export KO_VERSION=v0.1.6
helm upgrade --install kubernetes-ontology \
  ./charts/kubernetes-ontology \
  --namespace kubernetes-ontology \
  --create-namespace \
  --set image.tag="${KO_VERSION}"

Query the graph CLI or HTTP

kubectl -n kubernetes-ontology \
  port-forward svc/kubernetes-ontology 18080:18080

kubernetes-ontology \
  --server http://127.0.0.1:18080 \
  --status

Diagnose a Pod Evidence slice

kubernetes-ontology \
  --server http://127.0.0.1:18080 \
  --diagnose-pod \
  --namespace default \
  --name my-pod \
  --max-nodes 200

Topology viewer graph with Helm, PVC, PV, StorageClass, and CSI signals

Real viewer capture: a kind-style Helm workload graph with Service, config, identity, PVC, PV, StorageClass, CSIDriver, provisioner, Node, and Event evidence in one place.

Open viewer guide