Traffic Endpoints - kguardian

POST /pod/traffic

Insert a single observed traffic event. The kguardian controller calls this directly when a network event arrives from one of the eBPF ring buffers; external integrations rarely need it (prefer POST /pod/traffic/batch below for bulk). Duplicate events (same pod_ip, pod_port, traffic_type, traffic_in_out_ip, traffic_in_out_port, decision) are deduped server-side; the check is protocol-aware, branching on the event’s protocol rather than treating ip_protocol as a plain key column. The result reported back is inserted-or-Null. The audit forwarder (when evaluator.enabled: true) is fired only for events that were genuinely new.

Request

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "pod_name": "my-app-7d9f6b8c4-x5z2w",
  "pod_namespace": "production",
  "pod_ip": "10.244.1.5",
  "pod_port": "8080",
  "ip_protocol": "TCP",
  "traffic_type": "INGRESS",
  "traffic_in_out_ip": "10.244.2.10",
  "traffic_in_out_port": "52341",
  "decision": "ALLOW",
  "time_stamp": "2026-05-12T10:32:14.123456"
}

traffic_type is "INGRESS" (matches the upstream NetworkPolicy casing) or "EGRESS"; decision is "ALLOW" (eBPF observed an allow) or "DROP" (NetworkPolicy dropped the flow before it reached the destination, observed via the netpolicy-drop probe).

POST /pod/traffic/batch

Bulk variant taking a JSON array of the same shape. The controller batches up to 100 events at a time (or one second elapsed since last flush, whichever first); call sites talking to a remote broker should use this path to amortise the round-trip. Response is an integer count of the rows actually inserted after dedup.

GET /pod/traffic

Get a most-recent-first window of observed traffic rows, ordered (time_stamp DESC, uuid DESC) — newest first, with the UUID primary key as a tiebreak for microsecond-collision rows from a single batch ingest. The query is backed by the idx_pod_traffic_time_stamp index.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	5000	Cap rows returned. Clamped to `[1, 20000]`; values outside that range are silently clamped to the nearest bound. Non-numeric input returns 400.

Example

curl 'http://localhost:9090/pod/traffic?limit=100'

Response

[
  {
    "uuid": "234e5678-e89b-12d3-a456-426614174001",
    "pod_name": "my-app",
    "pod_namespace": "production",
    "pod_ip": "10.244.1.5",
    "pod_port": "35821",
    "ip_protocol": "TCP",
    "traffic_type": "EGRESS",
    "traffic_in_out_ip": "10.244.3.15",
    "traffic_in_out_port": "5432",
    "decision": "ALLOW",
    "time_stamp": "2026-05-12T10:32:14.123456"
  }
]

GET /pod/traffic/{name}

Get traffic for a single pod by name. The actix route captures name directly — no separate namespace path segment — so:

curl http://localhost:9090/pod/traffic/my-app-7d9f6b8c4-x5z2w

Same row shape as GET /pod/traffic above; same ordering. A name that doesn’t match any rows returns 404 with body "No data found". The frontend’s per-pod traffic view handles this transparently by falling back to an empty list.

​POST /pod/traffic

​Request

​POST /pod/traffic/batch

​GET /pod/traffic

​Query Parameters

​Example

​Response

​GET /pod/traffic/{name}