Inside the Kubernetes Cluster

The problem

Kubernetes' control plane is mostly invisible. When you run kubectl apply, the API server, scheduler and controllers do a lot of work you never see, which makes the system hard to teach and hard to reason about under pressure.

The approach

I built a local-first dashboard backed by a kind cluster. FastAPI uses the Kubernetes Python client to watch workload state and stream snapshots over Server-Sent Events to a Next.js interface. Live pod placement, ownership, readiness and replica counts sit beside clearly labelled conceptual explanations of scheduler and controller behaviour.

The result

A repeatable teaching tool that runs locally against a kind cluster. The repo includes one-command setup, architecture notes, a 30-minute presentation guide, a rehearsal checklist and API smoke tests for anyone who wants to run the demo.

Architecture

A local kind cluster runs one control-plane and two worker nodes. A small HTTP workload exposes pod identity and readiness. FastAPI watches Kubernetes resources and serves initial state, live SSE updates and namespace-scoped actions. Next.js separates live demo controls from a teaching view; conceptual control-plane cards are explicitly distinguished from discovered cluster data.

Run and verify

With Docker, kubectl, kind, make, Node.js and Python installed, the one-command setup creates the cluster, deploys the workload and starts both services. Automated rehearsal and API smoke checks help verify the session; the setup guide also documents reset and teardown.

Run locally

• make demo-all VERSION=v1
• make rehearsal-check
• make smoke-test

Source and setup

• Architecture and data flow
• Run the local demo
• Rehearsal checks