> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# See what is talking to what

> Read the live traffic graph for a supervisor — and learn to tell a quiet network from a stalled pipeline before you blame a policy.

By the end of this page you can answer "what does this workload actually connect to" from observed traffic rather than from intent — and, just as importantly, you can tell the difference between *nothing is talking* and *nothing is being recorded*.

This page starts where [Publish it on a public name](https://docs.celum.io/get-started/publish-it.md) ended: something of yours is reachable, and the obvious next question is by whom.

## What this changes on your cluster

Nothing. Every operation on this page is a read. It is the first station in this sequence where that is true, and worth saying plainly: you can explore all of it on a production supervisor without consequence.

## Before you start

* **The Flow Telemetry step**, from onboarding. Without it every view on this page is empty, correctly and unhelpfully.
* **Permission** `security:Read`, scoped `supervisor:<name>:security:*`.

## The shape of it

**Check the pipeline is alive → read the graph → judge whether to trust it → know what it cannot see.** Doing these in a different order is how people conclude the product is wrong when the ingestion simply stopped.

## Step 1 — Freshness, before anything else

An empty graph has two completely different causes and they look identical.

> [tab] Dashboard
>
> The Security page reports the window it queried and how fresh the data behind it is.

> [tab] API
>
> `GET /api/supervisors/{name}/security/flows/freshness` — last row timestamps and ingestion lag per table.

> [tab] MCP
>
> `get_flow_freshness`.

> [!WARNING]
>
> The tool's own description is the rule: *"Empty flow views with healthy components usually mean stalled ingestion — check this before blaming policies."* Every component can be green while nothing is being written. A HelmRelease reports that Helm succeeded, not that rows are arriving.

**Result:** a recent last-row timestamp and a small lag. If the lag is large or the timestamp is old, stop here — nothing below this line means anything until ingestion is moving.

## Step 2 — Read the graph

> [tab] Dashboard
>
> Security → **Topology**, then pick a namespace. The supervisor-wide read is the slowest view, so it does not run until you choose **all namespaces** yourself.

> [tab] API
>
> `GET /api/supervisors/{name}/security/flows/topology` — nodes with their listening ports (port, protocol, action, peers, flows, L7 protocol) and edges carrying a verdict plus policy coverage.

> [tab] MCP
>
> `get_flow_topology`.

![Security Topology scoped to namespace proj-team-k, with mode explore or author, window 1h, level workload, verdict filters allow, reject, unprotected and covered, a data-quality indicator and update time, a 48-hour timeline, counts of 39 workloads, 86 edges, denied flows and problem ports, and the start of the flow graph](https://mintcdn.com/celum-e0119be0/sA7S2Ajgv1l2CH1V/images/get-started/security-topology.png?fit=max\&auto=format\&n=sA7S2Ajgv1l2CH1V\&q=85\&s=c5598175b2de9fe39254e7e281c05b7f)

Topology for one namespace: the filters, the window, the counts, and the graph below them

Four parameters do most of the work:

| Parameter | What it does |
| - | - |
| `since` | the window. **Defaults to `1h`** — so the first graph you see is the last hour, not all time |
| `cluster` | scopes to a guest cluster; omit it for the supervisor itself |
| `by` | node granularity: `workload` (default — one node per Deployment or DaemonSet), `pod` (one per replica), or `node` (collapses edges to physical host pairs). An unknown value silently falls back to `workload` |
| `policy` | narrows to the edges a named policy covers, which is how you check a policy does what you meant |

`origin`, `node` and `interface` narrow further. `origin` is the one that matters on a shared namespace: it separates a supervisor's own workload from a vcluster's when both carry byte-identical labels.

**Result:** nodes and edges, each edge with a verdict and whether a policy covers it.

## Step 3 — Decide whether to believe it

A graph that renders is not automatically a graph that is right. Two checks tell you how much weight it will bear.

**Edge quality.** `get_flow_analytics` with `view=edge-quality` reports how many edges actually carry flow and byte data. Edges without either are inferences, not observations.

**Destination resolution.** An edge whose destination does not resolve to a workload is, in the words of Celum's own parity test, *"an edge to nowhere"* — and not an edge. That test exists because a correlator fault produced a graph that looked populated and resolved 0% of its destinations, while healthy clusters resolved nearly all of theirs. A low resolution rate is the single clearest sign the graph is lying to you.

> [!NOTE]
>
> **Count agreement is not agreement.** An edge is the triple (source, destination, port), and two clusters can each report twenty edges and share none of them. Whenever you compare two views — two clusters, two windows — compare the sets, never the totals.

## What the graph cannot see

Three blind spots, all structural. None of them is a fault you can fix by waiting, and each makes something look *unprotected* that is in fact protected.

**Workloads without a recognised name label are invisible to policy coverage.** The identity index keys on exactly four labels, in order:

```text theme={null}
vm.kubevirt.io/name · app.kubernetes.io/name · app · k8s-app
```

A pod carrying only a bespoke taxonomy label — `class=frontend`, say — is not indexed, so no policy coverage propagates to it however well it is protected. **If you want a workload to show as covered, give it an `app` label** alongside whatever else you use.

**Standard Kubernetes NetworkPolicies do not count toward coverage.** The coverage map walks `CiliumNetworkPolicy` and `CiliumClusterwideNetworkPolicy` only. Cilium enforces a plain `networking.k8s.io/v1` NetworkPolicy perfectly well — the traffic really is dropped — but the edge still paints as unprotected, because nothing looked for that kind.

**Charts that share one `app.kubernetes.io/name` across tiers collapse to a single key.** Coverage then keys on the shared name while the edges carry each tier's real workload name, the lookup misses, and intra-namespace edges between tiers stay unprotected on screen while being enforced in reality.

## What it can see that you might not expect

Denied traffic. A blocked connection produces neither conntrack bytes nor a policy reference, so the ordinary pipeline emits no row for it at all — which would make the first drop invisible exactly when you most want to see it, before any policy exists to explain it. Celum reads those from the raw flow table and grafts them on as synthetic reject edges, attached to the same graph node as that workload's other traffic rather than spawning a phantom beside it.

## What commonly goes wrong

| Symptom | Cause |
| - | - |
| The graph is empty and every component is green | check freshness. Green means Helm succeeded, not that rows are arriving |
| The graph only covers the last hour | `since` defaults to `1h` |
| An edge you know is protected paints as unprotected | a plain NetworkPolicy rather than a Cilium one, or a workload with no recognised name label |
| One tier of a Helm chart never shows as covered | its tiers share one `app.kubernetes.io/name`, so coverage collapses to one key |
| Two clusters report the same number of edges but disagree | compare the sets. Counts agree far more often than graphs do |
| Edges exist but lead nowhere | destination resolution has failed. Treat the graph as untrustworthy until it recovers |
| A supervisor workload and a vcluster workload look like one node | they share a namespace and labels. Scope by `origin` |

## Next

> [card] [Topology](https://docs.celum.io/security/topology.md)
>
> Node kinds, verdicts, grouping and filters in full.

> [card] [Flow analytics](https://docs.celum.io/security/flow-analytics.md)
>
> The aggregate views — namespace chords, FQDN egress, L7 and DNS breakdowns.

> [card] [Network policies](https://docs.celum.io/security/policies.md)
>
> Turning what you just observed into a policy, dry-run first.

> [card] [Flow telemetry](https://docs.celum.io/platform-health/flow-telemetry.md)
>
> The pipeline behind all of it, and why freshness is always the first check.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.