kubectl-gui/docs/cache-proposal.md

Cache Proposal for Kubectl Web GUI

Problem

With ~1600 pods, loading full lists from kubectl is slow. We need backend caching with background renewal so users are not blocked.

Ideas

1. In-Memory TTL Cache with Background Refresh

• Store parsed item lists in a Python dict with 5-minute TTL.
• A background thread (threading.Timer or asyncio) refreshes each resource type every 4 minutes.
• Users always read from memory; refresh is invisible.

2. Stale-While-Revalidate Pattern

• Serve cached data immediately.
• If cache is older than 3 minutes, trigger a background kubectl call to update it.
• User gets fast response; data updates shortly after.

3. Per-Resource Background Workers

• One lightweight thread per resource (pods, nodes, pvcs, configmaps).
• Each thread runs kubectl on its own interval (e.g., 4 min).
• Cache is always warm; no user request triggers kubectl unless bypass is used.

4. Cache Invalidation on Actions

• After delete/cordon/uncordon, invalidate only that resource's cache.
• Next load will refresh just that resource, not all.

5. Partial / Chunked Cache

• Cache full list but paginate in backend.
• Background refresh updates the full list; pagination stays fast.

Background Renewal Approach

• Use threading.Thread with a loop and time.sleep(240) per resource.
• Or use FastAPI startup event to spawn refresh tasks.
• Ensure thread-safe access to the shared cache dict (GIL helps, but use locks if needed).

Trade-offs

• Memory usage: ~1600 pods is small; acceptable.
• Staleness: 4-5 minutes is okay for a local GUI.
• Refresh impact: background only, so app stays responsive.