# IDEA.md – a simple Kubernetes explorer for the desktop This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on what was learned building Kube Explorer, an app for Windows and macOS written in Rust with Claude Code. ## 1. What to build A desktop app for the few things you actually do in your Kubernetes clusters, as a simpler alternative to `kubectl` commands and to full-featured programs like Lens. The app must be able to: - **read the clusters from kubeconfig** (`KUBECONFIG` or `~/.kube/config`), group the contexts, archive the ones you don't use, and – on Windows – also read the kubeconfig in WSL - **sign in with exec plugins** like `kubelogin` (Azure/AKS, including `devicecode`), also when the app was started from Finder, the Dock or the Start menu - show **live lists** of pods, deployments, services and namespaces, with a filter, sorting per column, copyable text and namespace favourites. Pods: namespace, name, ready, status, restarts, CPU and memory requests, age. Crashing pods in red, starting ones in yellow. - show **YAML** (colour-coded) and **Describe** (`kubectl describe`) for the selected item - follow **logs for a whole app**: every pod behind a deployment or service in one stream, one colour per pod, ANSI colours, pause, filter, copy - **port-forward to a service** (and to a pod), with a saved local port per service - **restart and scale** a deployment, with confirmation and extra protection in production - **tabs** for several clusters or views in the same window **Not** included: editing or applying YAML, other changes to the cluster than restart and scale, metrics and charts, extensions, Helm, listing clusters through the cloud provider's API, forwards that survive closing the app. ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **Rust**, a workspace with a core without an interface (`core`: kubeconfig, connections, resources, logs, forwarding, actions, exec, production rules) and the app (eframe/egui). Don't name the crates `kube-*` – `kube-core` already exists in kube-rs. - **`kube` (kube-rs) + `k8s-openapi`**, always upgraded together. `kube::runtime::watcher` and `reflector`/`Store` give a live cache per resource type and context – the right source for the tables. - **Important: networking on its own tokio runtime in the core, never on the UI thread.** - **TLS via rustls with `ring`, not `aws-lc`**, so cross-compiling to Windows works. `ring` contains C too; check Windows with `cargo xwin check`, not `cargo check --target`. - **egui**: `egui_extras` tables and `ScrollArea::show_rows` draw only visible rows, so big tables and long logs are fine. - Settings, saved ports, column widths and the last tab per context in the user's data directory. **Never read the user's kubeconfig in tests.** ## 3. Decisions that turned out to matter **Run the exec plugin yourself first.** kube-rs runs exec plugins with `Command::output()`: stderr is read only once the process has exited, and in interactive mode it's inherited – in a GUI app it goes nowhere. So the `devicecode` code never shows. The solution: 1. Find the plugin: the process's `PATH`, the login shell's `PATH` (read once with `$SHELL -ilc`, 5 s timeout), known directories (`/opt/homebrew/bin`, `/usr/local/bin`, `~/.azure-kubelogin`, on Windows WinGet Links and Azure CLI) and finally paths the user has pointed out. 2. Run the plugin once before connecting and read stderr line by line; parse the devicecode line and show the code with Copy Code and Open Browser. If the connection is cancelled, the process is killed. 3. Then let kube-rs connect with the same plugin, with an absolute path, the app's `PATH` in the environment and `interactiveMode: Never`. The token is then in the plugin's cache. 4. If the plugin is missing: show where the app looked and a button to point it out. If it fails: show its stderr in the error. 5. On Windows: no flashing console windows (`CREATE_NO_WINDOW`, and for kube-rs `KUBE_RS_UNSTABLE_CREATE_NO_WINDOW=1`, which is only safe for non-interactive runs). **Logs for a whole app.** kube-rs has `log_stream` per pod but no multi-pod mode. Build it: a watcher on pods with the app's selector starts and stops streams as pods come and go, and everything is merged into one channel. Show when a pod disappears. **Port-forward to a service the way kubectl does it.** kube-rs only forwards to pods. Choose yourself: the service's selector → the first pod that is Ready and not terminating → `targetPort` translated (number, a named port among the containers' ports, or the service's port). Local port: the same as the service's if free, otherwise one the system picks, on 127.0.0.1 only. Each local connection gets its own forward; if the pod is replaced, a new ready pod is chosen and the connection retried once. The same target twice starts no new forward. Disconnect, or a context that disappears, closes its forwards. **Restart like kubectl.** `Api::restart` sets `kube.kubernetes.io/restartedAt`, not kubectl's `kubectl.kubernetes.io/restartedAt`. Patch with kubectl's annotation yourself. Scale: `patch_scale` with `{"spec":{"replicas":n}}`. **Protection in production** (every changing action goes the same way): - A context is production if its name ends in `-p` or contains `prod`/`prd`, if its resource group contains `prod`, or if it's marked by hand. - Production is always visible: a red mark by the context name and a red frame around the workspace. - Restart and scale are always confirmed. The dialog shows cluster, namespace, deployment and, for scale, the current and new replica count. - In production the deployment's name must be typed before the button can be pressed. Scaling to 0 in production gets an extra warning. **Kubeconfig in WSL on Windows.** Read `~/.kube/config` in the distro via `\\wsl.localhost\\…` as text (kube-rs `read_from` makes `/home/…` relative on Windows) and rewrite the paths. Run exec plugins and `kubectl describe` through `wsl.exe -d --exec sh -lc`. Prefix clusters and users with `wsl:/` before merging; the Windows file wins on a clash. Ask `wsl.exe --list --running` every five seconds and read only distros that are running – reading a distro starts it – unless the user has chosen otherwise. **A fake API server for the tests.** Write a small API server over plain HTTP that answers `/version`, namespaces, pods, deployments and services, with list and watch using `resourceVersion`, where tests can add and remove objects while the watch runs, that follows logs (including the end at a restart) and that speaks port-forward over WebSocket (`v4.channel.k8s.io`) to an echo. Everything except the sign-in itself can then be tried without a real cluster – and screenshots can be taken against it without any real names showing. **Developer hooks from day one**: `_CONFIG_DIR` (a separate settings directory), `_SCREENSHOT=file.png` from the real window, and a headless test that renders against the fake server with variables for the context name, a selected pod, the log panel, port-forward, sorting, Describe, tabs, the namespace list, the error dialog and the production confirmation. ## 4. Pitfalls - **Don't trust kube-rs to show the exec plugin's output** – see section 3. - **Don't assume a GUI app has the shell's `PATH`.** From Finder, the Dock or the Start menu, neither `kubelogin` nor `az` is found. - **Don't forget eframe's links feature.** With `default-features = false`, `ctx.open_url` does nothing without the `links` feature; egui only logs a warning. Test that the button asks to open the address. - **Don't use `→` or other arrows in the interface.** egui's bundled font lacks them and draws empty boxes. Write words. - **Don't let the tests read the user's kubeconfig** – they'd connect to real clusters and start kubelogin. Give the app its own file. - **Test port-forward on a high, process-dependent port**, not 80 or 8080: the forward binds the same port locally, and parallel tests clash. - **Click menu buttons in UI tests with a real pointer event**, not AccessKit's click. - **Don't build in a `target/` on a Windows drive from WSL**, and write screenshots from the Windows exe to a directory Windows can reach. - **A "Forbidden" at "All namespaces"** means the user may not list across the whole cluster – show it clearly instead of an empty list. - **A token without `expirationTimestamp` is never refreshed** by kube-rs. ## 5. Requirements and measurements - The lists update within a few seconds when a pod is restarted or scaled outside the app, without anything being done in the app. - The logs follow a rollout: new pods are picked up, old ones let go. - The port-forward survives a rollout: the next connection goes to a new pod. - Kube Explorer had 57 tests when port-forward was done (34 in the core, 23 in the app), and around 73 later, all green three runs in a row. - The macOS package around 14–16 MB. ## 6. How it's verified - `cargo clippy --workspace --all-targets` with no warnings, `cargo test --workspace`, and `cargo xwin check --workspace --target x86_64-pc-windows-msvc`. - **Tests over the network against the fake server**: lists and watch, logs through a restart, port-forward with real TCP through the local port and a pod switch, the production rules. - **Fake exec plugins** (sh scripts) showing that the code appears before the plugin finishes, that the token reaches the server, that the absolute path is used, that stderr ends up in the error and that the plugin is killed on cancel. - **UI tests without a window** (`egui_kittest`) and **screenshots** of every new view against the fake server. - What needs a real cluster with sign-in – kubelogin, devicecode, a real rollout – becomes a verification task with a checklist. ## 7. Way of working - **Research first**: similar programs (Lens, Freelens, Headlamp, Aptakube, k9s), what users complain about (Electron weight, account requirements, exec plugins not found) and how the Rust ecosystem handles logs, port-forward and restart. Mark what was checked against a source and what is judgement. - **Ask about the real decisions before building anything**: which clusters and which sign-in the first version should support, and how careful the app should be in production. - **One task at a time**, with the measurement in the closing comment and a checklist for what can only be tried against a real cluster. ## 8. The prompt > Build a desktop app for [Windows and macOS] in [Rust with eframe/egui and kube-rs] to explore my Kubernetes clusters: live lists of pods, deployments, services and namespaces, YAML and Describe, logs for every pod in an app, port-forward to a service, and restart and scale of a deployment with extra protection in production. It should read kubeconfig and sign in with the same exec plugins as kubectl, [e.g. kubelogin for AKS], also when started from Finder or the Start menu. > > Read all of IDEA.md below first. It describes the features, the architecture, the decisions that turned out to matter and the pitfalls to avoid. > > Work like this: > 1. Research similar programs and write a plan. Ask me which clusters and which sign-in to support, and how careful the app should be in production. > 2. Build a fake API server for the tests first, and never let the tests read my kubeconfig. > 3. Run networking on its own runtime, never on the UI thread. > 4. Review every new view with a screenshot against the fake server. > 5. Leave what needs my real cluster and my sign-in as a checklist for me. > > My clusters: [cloud provider, sign-in mode, how production clusters can be recognized by name]. > > [paste IDEA.md here]