# IDEA.md – en enkel Kubernetes-utforskare för skrivbordet Det här är en fristående uppdragsbeskrivning. Ge den i sin helhet till Claude Code (eller ett liknande verktyg) för att bygga en egen implementation. Den bygger på erfarenheterna från Kube Explorer, en app för Windows och macOS byggd i Rust med Claude Code. ## 1. Vad som ska byggas En skrivbordsapp för de få saker man faktiskt gör i sina Kubernetes-kluster, som ett enklare alternativ till `kubectl`-kommandon och till fullmatade program som Lens. Appen ska kunna: - **läsa klustren ur kubeconfig** (`KUBECONFIG` eller `~/.kube/config`), gruppera kontexterna, arkivera de man inte använder, och – på Windows – också läsa kubeconfig i WSL - **logga in med exec-tillägg** som `kubelogin` (Azure/AKS, även `devicecode`), också när appen startats från Finder, Dock eller Startmenyn - visa **levande listor** över pods, deployments, services och namespaces, med filter, sortering per kolumn, kopierbar text och namespace-favoriter. Pods: namespace, namn, ready, status, omstarter, CPU- och minnesbegäran, ålder. Kraschande poddar i rött, startande i gult. - visa **YAML** (färgkodad) och **Describe** (`kubectl describe`) för det markerade - följa **loggar för en hel app**: alla poddar bakom en deployment eller service i en ström, en färg per pod, ANSI-färger, paus, filter, kopiering - **port-forward till en service** (och till en pod), med sparad lokal port per service - **starta om och skala** en deployment, med bekräftelse och extra skydd i produktion - **flikar** för flera kluster eller vyer i samma fönster Ingår **inte**: att redigera eller applicera YAML, andra ändringar i klustret än restart och scale, mätvärden och grafer, tillägg, Helm, listning av kluster via molnleverantörens API, forwards som överlever att appen stängs. ## 2. Stack och arkitektur Det som är **viktigt** är markerat; resten går att byta. - **Rust**, en workspace med en kärna utan gränssnitt (`core`: kubeconfig, anslutningar, resurser, loggar, forward, åtgärder, exec, prod-regler) och appen (eframe/egui). Döp inte craterna `kube-*` – `kube-core` finns redan i kube-rs. - **`kube` (kube-rs) + `k8s-openapi`**, alltid uppgraderade tillsammans. `kube::runtime::watcher` och `reflector`/`Store` ger en levande cache per resurstyp och kontext – rätt källa för tabellerna. - **Viktigt: nätverket på en egen tokio-runtime i kärnan, aldrig på UI-tråden.** - **TLS via rustls med `ring`, inte `aws-lc`**, så att korsbygget till Windows fungerar. Även `ring` innehåller C; kontrollera Windows med `cargo xwin check`, inte `cargo check --target`. - **egui**: `egui_extras` tabeller och `ScrollArea::show_rows` ritar bara synliga rader, så stora tabeller och långa loggar går bra. - Inställningar, sparade portar, kolumnbredder och senaste flik per kontext i användarens datakatalog. **Läs aldrig användarens kubeconfig i testerna.** ## 3. Beslut som visade sig avgörande **Kör exec-tillägget själv först.** kube-rs kör exec-tillägg med `Command::output()`: stderr läses först när processen avslutats, och i interaktivt läge ärvs den – i en GUI-app hamnar den ingenstans. `devicecode`-koden syns alltså aldrig. Lösningen: 1. Hitta tillägget: processens `PATH`, login-skalets `PATH` (läs en gång med `$SHELL -ilc`, tidsgräns 5 s), kända kataloger (`/opt/homebrew/bin`, `/usr/local/bin`, `~/.azure-kubelogin`, på Windows WinGet Links och Azure CLI) och sist sökvägar användaren pekat ut. 2. Kör tillägget en gång före anslutningen och läs stderr rad för rad; tolka devicecode-raden och visa koden med Copy Code och Open Browser. Avbryts anslutningen dödas processen. 3. Låt sedan kube-rs ansluta med samma tillägg, med absolut sökväg, appens `PATH` i miljön och `interactiveMode: Never`. Token ligger då i tilläggets cache. 4. Saknas tillägget: visa var appen letat och en knapp för att peka ut det. Misslyckas det: visa dess stderr i felet. 5. På Windows: inga blinkande konsolfönster (`CREATE_NO_WINDOW`, och för kube-rs `KUBE_RS_UNSTABLE_CREATE_NO_WINDOW=1`, som bara är säkert för icke-interaktiva körningar). **Loggar för en hel app.** kube-rs har `log_stream` per pod men inget läge för många poddar. Bygg det: en watcher på poddar med appens selector startar och stoppar strömmar när poddar kommer och går, och allt slås ihop i en kanal. Visa när en pod försvinner. **Port-forward till en service som kubectl gör det.** kube-rs forwardar bara till poddar. Välj själv: servicens selector → första podden som är Ready och inte på väg bort → `targetPort` översatt (nummer, namngiven port bland containrarnas portar, eller servicens port). Lokal port: samma som servicens om den är ledig, annars en systemvald, bara på 127.0.0.1. Varje lokal anslutning får en egen forward; byts podden ut väljs en ny pod som är redo och anslutningen görs om en gång. Samma mål två gånger startar ingen ny forward. Disconnect eller en kontext som försvinner stänger dess forwards. **Restart som kubectl.** `Api::restart` sätter `kube.kubernetes.io/restartedAt`, inte kubectl:s `kubectl.kubernetes.io/restartedAt`. Patcha själv med kubectl:s annotation. Scale: `patch_scale` med `{"spec":{"replicas":n}}`. **Skydd i produktion** (alla ändrande åtgärder går samma väg): - En kontext är prod om namnet slutar på `-p` eller innehåller `prod`/`prd`, om resursgruppen innehåller `prod`, eller om den markerats för hand. - Prod syns alltid: röd markering vid kontextnamnet och röd ram runt arbetsytan. - Restart och scale bekräftas alltid. Dialogen visar kluster, namespace, deployment och vid scale nuvarande och nytt antal repliker. - I prod måste deploymentens namn skrivas in innan knappen går att trycka på. Scale till 0 i prod får en extra varning. **Kubeconfig i WSL på Windows.** Läs `~/.kube/config` i distron via `\\wsl.localhost\\…` som text (kube-rs `read_from` gör `/home/…` relativ på Windows) och skriv om sökvägarna. Kör exec-tillägg och `kubectl describe` genom `wsl.exe -d --exec sh -lc`. Ge kluster och användare prefixet `wsl:/` före sammanslagningen; Windows-filen vinner vid krock. Fråga `wsl.exe --list --running` var femte sekund och läs bara distros som kör – att läsa en distro startar den – utom om användaren valt det. **En påhittad API-server för testerna.** Skriv en liten API-server över ren HTTP som svarar på `/version`, namespaces, pods, deployments och services, med list och watch med `resourceVersion`, där tester kan lägga till och ta bort objekt medan watchen pågår, som följer loggar (även slutet vid en omstart) och som talar port-forward över WebSocket (`v4.channel.k8s.io`) till ett eko. Allt utom själva inloggningen kan då provas utan ett riktigt kluster – och skärmbilder kan tas mot den utan att några riktiga namn syns. **Utvecklarhjälp från dag ett**: `_CONFIG_DIR` (egen inställningskatalog), `_SCREENSHOT=fil.png` från det riktiga fönstret, och ett headless-test som renderar mot den påhittade servern med variabler för kontextnamn, markerad pod, loggpanel, port-forward, sortering, Describe, flikar, namespace-listan, feldialog och prod-bekräftelse. ## 4. Fallgropar - **Lita inte på att kube-rs visar exec-tilläggets utskrift** – se avsnitt 3. - **Anta inte att en GUI-app har skalets `PATH`.** Från Finder, Dock eller Startmenyn hittas varken `kubelogin` eller `az`. - **Glöm inte eframes funktion för länkar.** Med `default-features = false` gör `ctx.open_url` ingenting utan funktionen `links`; egui loggar bara en varning. Testa att knappen ber om att öppna adressen. - **Använd inte `→` eller andra pilar i gränssnittet.** egui:s medföljande typsnitt saknar dem och ritar tomma rutor. Skriv ord. - **Låt inte testerna läsa användarens kubeconfig** – då ansluter de till riktiga kluster och startar kubelogin. Ge appen en egen fil. - **Testa port-forward på en hög port som beror på processen**, inte 80 eller 8080: forwarden binder samma port lokalt, och parallella tester krockar. - **Klicka på menyknappar i UI-tester med en riktig pekarhändelse**, inte med AccessKit:s klick. - **Kör inte bygget i en `target/` på en Windows-disk från WSL**, och skriv skärmbilder från Windows-exe:n till en katalog Windows når. - **Ett "Forbidden" vid "All namespaces"** betyder att användaren inte får lista i hela klustret – visa det tydligt i stället för en tom lista. - **Token utan `expirationTimestamp` förnyas aldrig** av kube-rs. ## 5. Krav och mått - Listorna uppdateras inom några sekunder när en pod startas om eller skalas utanför appen, utan att något görs i appen. - Loggarna följer en rollout: nya poddar tas med, gamla släpps. - Port-forwarden överlever en rollout: nästa anslutning går till en ny pod. - Kube Explorer hade 57 tester när port-forward var klar (34 i kärnan, 23 i appen), och runt 73 senare, alla gröna tre körningar i rad. - macOS-paketet runt 14–16 MB. ## 6. Så verifieras det - `cargo clippy --workspace --all-targets` utan varningar, `cargo test --workspace`, och `cargo xwin check --workspace --target x86_64-pc-windows-msvc`. - **Tester över nätet mot den påhittade servern**: listor och watch, loggar genom en omstart, port-forward med riktig TCP genom den lokala porten och byte av pod, prod-reglerna. - **Låtsade exec-tillägg** (sh-skript) som visar att koden syns innan tillägget är klart, att token når servern, att den absoluta sökvägen används, att stderr hamnar i felet och att tillägget dödas vid avbrott. - **UI-tester utan fönster** (`egui_kittest`) och **skärmbilder** av varje ny vy mot den påhittade servern. - Det som kräver ett riktigt kluster med inloggning – kubelogin, devicecode, en riktig rollout – blir ett verifieringsärende med en checklista. ## 7. Arbetssätt - **Research först**: liknande program (Lens, Freelens, Headlamp, Aptakube, k9s), vad användare klagar på (Electron-tyngd, kontokrav, exec-tillägg som inte hittas) och hur Rust-ekosystemet löser loggar, port-forward och restart. Markera vad som är kontrollerat i källa och vad som är bedömning. - **Fråga om de verkliga besluten innan något byggs**: vilka kluster och vilken inloggning den första versionen ska stödja, och hur försiktig appen ska vara i produktion. - **Ett ärende i taget**, med mätningen i avslutskommentaren och en checklista för det som bara kan provas mot ett riktigt kluster. ## 8. Prompten > Bygg en skrivbordsapp för [Windows och macOS] i [Rust med eframe/egui och kube-rs] för att utforska mina Kubernetes-kluster: levande listor över pods, deployments, services och namespaces, YAML och Describe, loggar för alla poddar i en app, port-forward till en service, och restart och scale av en deployment med extra skydd i produktion. Den ska läsa kubeconfig och logga in med samma exec-tillägg som kubectl, [t.ex. kubelogin för AKS], också när den startas från Finder eller Startmenyn. > > Läs hela IDEA.md nedan först. Den beskriver funktionerna, arkitekturen, de beslut som visade sig avgörande och fallgroparna att undvika. > > Arbeta så här: > 1. Gör research på liknande program och skriv en plan. Fråga mig om vilka kluster och vilken inloggning som ska stödjas, och hur försiktig appen ska vara i produktion. > 2. Bygg en påhittad API-server för testerna först, och låt aldrig testerna läsa min kubeconfig. > 3. Kör nätverket på en egen runtime, aldrig på UI-tråden. > 4. Granska varje ny vy med en skärmbild mot den påhittade servern. > 5. Lämna det som kräver mitt riktiga kluster och min inloggning som en checklista till mig. > > Mina kluster: [molnleverantör, inloggningsläge, hur produktionskluster känns igen på namnet]. > > [klistra in IDEA.md här]