k8s-pod-foamtree

k8sfoams is a local, read-only dashboard that answers one question: where is my cluster's requested CPU and memory actually going, and how much room is left on each node?

It visualizes resource requests — what the scheduler reserves — not live usage. That makes it a tool for spotting over-requesting pods and idle headroom, not a performance monitor. It runs on your laptop, reads ~/.kube/config (or $KUBECONFIG) with the standard Kubernetes client, and needs no in-cluster deployment and no metrics-server.

How it works

1. Lists nodes (status.capacity) and all non-terminated pods. Pods in Succeeded/Failed are excluded — they still report requests via the API but no longer reserve anything.
2. Parses quantities with the Kubernetes client's parse_quantity — CPU to millicores, memory to decimal kB. A pod's effective request is max(sum(regular containers), max(init containers)) — init containers run sequentially, so they are maxed, not summed. Native sidecars (init containers with restartPolicy: Always) keep running, so they count as regular containers and add to every init container started after them. This is what the scheduler actually reserves.
3. Nests the result node → pod → container and adds a synthetic empty child per node for free capacity, then serves it as JSON.
4. A React single-page app fetches CPU and memory in parallel, merges them, and renders. esbuild compiles its .jsx files and bundles React into one bundle.js, which the Python package ships, so no script is loaded from a CDN. The view auto-refreshes every 60 seconds by default.

2D map

A squarified treemap. Each node is a square box, each pod is a foam inside it. A pod with more than one container is split into sub-foams. The empty foam is unused (free) capacity on that node. Pick CPU or Memory with the Resource control.

3D cubes

An isometric view: one plate per node, one cube per pod. A cube encodes both resources at once:

• width × depth (footprint) → CPU request
• height → memory request
• color → node

Both dimensions are square-root scaled, so a 10× larger pod is not 10× wider. Because a cube already shows both resources, the CPU/Memory picker is disabled in 3D and a Zoom slider takes its place.

Switch views with the sidebar View control or the 2D/3D pill in the header. It is client-side state — no flag, no restart. The scene is drawn with WebGL (three.js), so it stays smooth with thousands of pods: drag to orbit, scroll or use the slider to zoom, hover a cube for its pod, click a plate for its node. Where WebGL is turned off the 3D view says so, and the 2D map shows the same data.

Controls

• Memory unit: MiB, GiB (default), or TiB.
• Color by: Node (default) gives each node its own hue; QoS colors each pod by its QoS class. See QoS & eviction risk.
• Context: the sidebar lists every context from your kubeconfig, active one first, tagged by provider. Switching only changes the context inside the k8sfoams web server — your ~/.kube/config file is never modified.
• Refresh: slider from 5 to 600 seconds, plus a Refresh now button.
• Filter: the header query bar highlights matching pods and dims the rest — nothing is removed from the view. See Filtering for the full grammar.
• Focus: click a node to open an overlay listing its pods with per-pod CPU/memory and container breakdown.

Node health

Free capacity on a node that refuses pods is not really free. A node that is cordoned, under pressure, or carrying a NoSchedule taint has its idle foam hatched with diagonal warning stripes (the plate surface in 3D), gets a warning badge next to the utilization percentage, and lists a Node health key in the sidebar counting how many nodes are affected by each reason. A healthy cluster looks exactly as it did before — nothing is added.

Two rules are worth knowing:

• PreferNoSchedule never marks a node. It is a soft hint the scheduler is free to ignore, so it is listed in the focus overlay but does not stripe.
• The cordon taint is folded into cordoned. Kubernetes adds node.kubernetes.io/unschedulable:NoSchedule itself when you cordon; reporting it as a taint too would mark the same node twice for one fact, so it is dropped from the taint list.

The sidebar's Node health panel counts nodes per warning. Click a row to highlight those nodes and their pods in 2D and 3D; every other node dims. This sets the query to health:<warning>; click the row again to clear it.

Click a node to open the focus overlay: a Scheduling section spells out every reason and lists each taint as key=value with its effect. Worst reason wins the header pill — a cordoned node under memory pressure reads as SCHEDULING-DISABLED, because that is what actually keeps pods off it.

Audit & hygiene

Every pod is checked against four best-practice rules. A pod that breaks one gets a small warning glyph in the top-right corner of its box (hover it for the reasons). The sidebar's Audit & Hygiene panel counts the affected pods per rule. Click a row to highlight those pods in 2D and 3D. This sets the query to audit:<rule>; click the row again to clear it. A clean cluster reads No issues found.

Three details are worth knowing:

• Init containers are not audited. They finish before the app runs, so their requests and limits say nothing about how the pod behaves once it is running.
• CPU limits are not required. Only a missing memory limit is flagged. A memory leak without a limit can take the whole node down; a CPU spike without a limit only gets throttled.
• Ratio asymmetry ignores small pods. A sidecar asking for 5% of the CPU and almost no memory has an extreme ratio, but it leaves no meaningful capacity stranded.

QoS & eviction risk

Under memory pressure the kubelet evicts pods by QoS class. Set Color by → QoS in the sidebar to color every pod box (2D) and cube (3D) by its class. Node cards and plates turn a neutral slate, so only the pods carry color.

The sidebar's QoS & Eviction Risk panel counts pods per class, riskiest first. It is shown in either color mode, and a class with no pods still reads 0. Click a row to highlight those pods; this sets the query to qos:<Class>. Click it again to clear.

The class is read from the pod's status.qosClass, which the kubelet sets. It is not recomputed from requests and limits. A pod with no reported class renders neutral and is not counted.

Filtering

The query bar in the header is a highlighter, not a filter of last resort: matching pods glow, everything else dims. No pod, node or box ever leaves the layout, so the shape of the cluster stays comparable while you narrow down. Once the query is non-empty and valid, a live counter inside the input reads N / M pods (and turns red at 0).

Type whitespace-separated tokens. All tokens are ANDed — a pod must satisfy every one of them:

ns:kube-system qos:Burstable app=frontend

An empty query matches everything. A query that contains a malformed token is inert: nothing dims, and the offending tokens are listed under the bar with the reason. Half-typing ns: can never blank the view.

Token reference

Examples

Every pod named like nginx, anywhere:

nginx

Pods in kube-system that run init containers:

ns:kube-system has:init-containers

Everything the scheduler can evict first, on the worker pool:

qos:BestEffort node:worker-*

Frontend pods that are not in production, named like api:

app=frontend env!=prod api

One specific node — globs are anchored, so dots are literal, not wildcards:

node:ip-10-0-1-5.ec2.internal

All nodes in an AZ suffix, plus a namespace:

node:*-eu-west-1a ns:payments

Guaranteed pods carrying a label value with a space:

qos:Guaranteed app="my app"

Match a pod name that looks like a filter token — leading quotes make the whole token literal text:

"web:1"

Without the quotes, web:1 is read as an unknown filter prefix and reported as an error.

Sharp edges

• != wins over =. env!=prod is one inequality, never env! equals prod.
• A filter prefix must be a bare word before :. app=ns:x is a label selector for key app, value ns:x — not a namespace filter.
• Only node: and health: can dim a node. Node plates and boxes stay in the layout either way; pod-level terms dim pods, never their node.
• A missing label matches !=. env!=prod highlights pods with env: staging and pods with no env label at all — the Kubernetes selector semantics.
• Every problem is reported at once. The parser never stops on the first bad token, so a three-error query lists three errors.

Errors you can hit

Focusing the input opens a popover with the same token list; it is replaced by the error list while a token is malformed. The × on the right clears the query.

Export

The download button in the header, next to Refresh, saves what you are looking at — for capacity-planning decks, Slack updates and incident reports. Everything is built in the browser; nothing extra is fetched from the cluster.

Images keep the current metric, colours, tweaks, query dimming and pinned workload, and carry a title band with the context, totals and refresh time. Reports always list every pod; with a query active, matched says which ones it selected. Files are named k8sfoams-<context>-<2d|3d|report>-YYYYMMDD-HHmm.<ext>. Web fonts are not embedded, so exported images fall back to system fonts.

Extended resources

Besides CPU and memory, the Resource picker lists every extended resource a node in the current context can allocate: GPUs and other device-plugin resources (nvidia.com/gpu, amd.com/gpu), ephemeral-storage and HugePages (hugepages-2Mi, hugepages-1Gi). When there is at least one, the two-button toggle becomes a dropdown. Switching to a context without the selected resource falls back to CPU.

• 2D map. Nodes are sized by how much of the resource they can allocate, and pods by what they request. Nodes without the resource are hidden, and the header counts them.
• Fragmentation. For devices the header also shows the free units cluster-wide and the largest free block on one node. For example, 6 free GPUs spread 2 + 2 + 2 cannot run a 4-GPU job.
• 3D cubes. Cubes keep plotting CPU × Memory. Pods requesting the selected resource stay lit and the rest dim. Plates show used/allocatable for it.
• Node health. stranded devices marks a node that still has free devices but has 90% or more of its CPU or memory requested, so no pod can reach those devices. Query it with health:stranded-devices.

Requests follow the scheduler's rules, including init containers and native sidecars. An extended resource set only as a limit counts as a request of the same size. Node sizes come from status.allocatable, for CPU and memory too, so kube- and system-reserved capacity is not drawn as free space.

HTTP API

Installation

Prerequisites

Install uv package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

Install from source

Building the UI from source also needs Node.js 18 or newer; make run and make build build it with make web. The PyPI package already contains the built UI.

# Install dependencies and the package in development mode
make restore_dev

# Or install without dev dependencies
make restore

Install via PyPi

pip install k8sfoams
# or with uv
uv pip install k8sfoams

Run k8s-pod-foamtree

After installation, run the application:

# Using make
make run

# Or directly
k8sfoams

# Or with uv run
uv run k8sfoams

Command lines arguments

• host: host IP address on which server listen, default is 127.0.0.1
• port: port number on which server listen, default is 8080
• d: turn on debug mode when server starts

Example:

k8sfoams --host 0.0.0.0 --port 8080 -d

Development

Running tests

# Run all tests (type checking, linting, security, unit tests)
make tests

# Run individual test suites
make unit_tests
make static_code_analysis
make check_types
make bandit

Frontend

The UI sources are the .jsx files in k8sfoam/src/frontend; main.js lists them in load order. esbuild compiles them into bundle.js, which is gitignored.

make web        # npm ci + one build
npm run watch   # rebuild on every save while the server runs

CI/CD targets

For CI/CD environments (GitHub Actions, etc.), use these targets that work with system Python:

make restore_ci   # Install dependencies with --system flag
make tests_ci     # Run all tests without uv run prefix

Building the package

make build

Clean build artifacts

make clean