> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/dstl8-docs/topology.md).

# Topology

Dstl8 captures the resource topology of your connected Kubernetes clusters — workloads, pods, services, ingresses, nodes, and the relationships between them. You can explore it visually in the web UI, browse it in the terminal, and query blast radius from the CLI. Möbius uses the same graph to reason about impact across the cluster during investigations.

### How it works

The cluster component of the [ControlTheory Kubernetes agent](/controltheory-documentation/dstl8-docs/sources/kubernetes.md) collects a topology snapshot roughly every **30 minutes** and sends it to Dstl8. That means:

* Topology requires a **Kubernetes source** with the cluster agent installed and running.
* A freshly installed agent can take up to half an hour to produce its first snapshot.
* Every topology view shows a freshness badge — **"Last scanned 12m ago"** — which turns to **"Stale — agent may be down"** if snapshots stop arriving.

## In the web UI

Open a workspace and click **Topology** in the sidebar. The link appears once the workspace has a Kubernetes source assigned and at least one cluster is reporting topology data. If the workspace spans multiple clusters, use the cluster selector in the header to switch between them; the header also shows totals (nodes · namespaces · workloads · pods).

Each Kubernetes source's detail page also has its own **Topology** tab with the same views, scoped to just that source's clusters.

There are two views, switched with the **Explorer** / **Graph** tabs.

### Explorer

A hierarchical tree of the cluster with a detail pane beside it:

* **Cluster** → **Nodes** (with pod counts per node) and a **Namespaces** section
* Each namespace groups its resources: Deployments, StatefulSets, DaemonSets, CronJobs, Jobs, Services, Ingresses, and Standalone Pods
* Pods are listed under their owning workload (ReplicaSets are collapsed away), with restart counts; Deployments and StatefulSets show `ready/desired` badges (e.g. `3/5`)

Type in the **Filter by name…** box to find a resource — the tree narrows to matches and their ancestors auto-expand. Click any item to see its details on the right: current status, metadata (labels, annotations, readiness, restarts), its **Relationships** — each one a clickable link that jumps to the related entity — and the entity's recent logs and log patterns from the last hour.

### Graph

An interactive network diagram of the same data:

* **Namespaces start collapsed** as summary boxes ("12 pods · 4 deploy · 1 sts · 2 svc") — click one to expand it in place, or use **Expand all** / **Collapse all**.
* **Filter by kind** with the toggle badges above the graph (Deployment, StatefulSet, DaemonSet, ReplicaSet, Job, CronJob, Pod, Service, Ingress). ReplicaSets and Jobs are hidden by default to reduce clutter.
* **Search** with the *Find workload, pod, service…* box.
* Scroll to zoom, drag the background to pan, drag nodes to rearrange. Click a node to open its detail panel; click the background to close it.

Nodes are color-coded by kind and carry a status dot (green healthy, amber pending/degraded, red failed, gray unknown). Edges are color-coded by relationship:

| Relationship | Meaning                                           |
| ------------ | ------------------------------------------------- |
| `owns`       | Ownership chain (Deployment → ReplicaSet → Pod)   |
| `targets`    | A Service targeting the pods it load-balances     |
| `routes_to`  | An Ingress routing traffic to a Service           |
| `runs_on`    | A Pod scheduled on a Node                         |
| `uses`       | A Pod referencing a ConfigMap or Secret           |
| `contains`   | Cluster containment (cluster → nodes, namespaces) |

### Reading blast radius

Select any entity and its detail panel lists both directions: outgoing relationships (what it owns, targets, or uses) and incoming ones (what runs on it, targets it, or depends on it). Selecting a Node, for example, immediately shows every pod scheduled on it; selecting a Service shows the ingresses routing to it and the pods behind it. That's the "what breaks if this goes away" question, answered before you drain the node.

{% hint style="info" %}
**Nothing showing?** The empty state means the workspace has no Kubernetes source yet, or the cluster agent hasn't produced a snapshot. Add a [Kubernetes source](/controltheory-documentation/dstl8-docs/sources/kubernetes.md), and give a fresh agent up to 30 minutes.
{% endhint %}

## In the TUI

`dstl8 tui` adds a **Topology** tab to any workspace that has a Kubernetes source. It renders the same resource tree as the web Explorer, navigable from the keyboard:

| Key     | Action                                      |
| ------- | ------------------------------------------- |
| `↑` `↓` | Move through the resource tree              |
| `Enter` | Expand / collapse the selected entity       |
| `→`     | Expand                                      |
| `←`     | Collapse / jump to parent                   |
| `c`     | Switch cluster (when several have topology) |

## From the CLI

`dstl8 topology` (alias: `topo`) exposes the graph for scripts, quick checks, and AI agents. All subcommands accept `--json` for raw output.

```bash
dstl8 topology clusters                          # list clusters that have topology data
dstl8 topology view                              # show the cluster resource tree
dstl8 topology view my-cluster -n payments       # one cluster, one namespace
dstl8 topology view --kinds deployment,service   # filter by kind
dstl8 topology impact deployment/checkout/payment-api   # blast radius for a workload
dstl8 topology impact node/worker-2 --direction dependents
```

### `dstl8 topology view`

Prints the resource tree (alias: `tree`). With one cluster reporting, the cluster argument is optional.

| Flag              | Description                                                 |
| ----------------- | ----------------------------------------------------------- |
| `--kinds`         | Comma-separated kind filter (e.g. `deployment,pod,service`) |
| `-n, --namespace` | Restrict to one namespace                                   |
| `--json`          | Raw JSON output                                             |

### `dstl8 topology impact`

Shows what depends on a component and what it depends on. The argument is `kind/namespace/name` — omit the namespace for cluster-scoped kinds:

```bash
dstl8 topology impact deployment/checkout/payment-api
dstl8 topology impact node/worker-2
```

| Flag            | Description                                              |
| --------------- | -------------------------------------------------------- |
| `-c, --cluster` | Cluster key (from `dstl8 topology clusters`)             |
| `--depth`       | Traversal depth, 1–5 (default 3)                         |
| `--direction`   | `dependents`, `dependencies`, or `both` (default `both`) |
| `--json`        | Raw JSON output                                          |

Typical uses: check what's riding on a node before draining it, list everything downstream of a service before a risky deploy, or let an MCP-connected agent pull `--json` impact data while investigating an incident.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/dstl8-docs/topology.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.