kctl-tui/SPEC.md

SPEC: kctl-tui — Kubernetes Entry-Point TUI

1. Goal

A single terminal tool as the central entry point for everyday Kubernetes work, bundling the most common workflows currently done via long kubectl/k9s/aws-cli commands, operable through a text UI (arrow keys, Esc, Tab) instead of long typed commands.

Target platform: Linux / WSL (primary usage scenario, since split panes require a real terminal multiplexer). Native Windows (without WSL) is possible but with reduced split-view functionality (see 3.6).

Technology decision: Go + Bubble Tea (see section 5).

2. Terminology

Term	Meaning
Context	Kubernetes cluster connection (kubectl config get-contexts)
Namespace	Logical subdivision within a cluster/context
Deployment	Controls the pods of a service; its name does not have to match the namespace name
Pod	Running instance, automatically generated name, not needed manually for the restart workflow
Rollout Restart	Rolling restart of all pods of a deployment according to the RollingUpdate strategy — not a simultaneous hard-kill of all pods, except with 1 replica or the Recreate strategy
Control pane	The top tmux pane running the Go tool itself (menu for redeploy/secrets)
Status panes	The two lower tmux panes, each running a k9s instance
Team label	Any freely configurable namespace label used to group namespaces by team/ownership (key and values are project-specific, kept generic here)

3. Functional Requirements

3.1 Start navigation (hierarchical, with defaults)

Order at program start (outside tmux, "full" mode):

1. Context selection — list of all available contexts, currently active context pre-selected at the top as "(current)".
2. Team selection — list of all distinct values of a configurable namespace label (key freely configurable, e.g. <organization>/<label-name>), current team value pre-selected. A "no filter" option is available.
3. Namespace selection — filtered by the chosen team label value, active namespace pre-selected.
4. Main view — directly starts the tmux session with the three panes (see 3.3).

Navigation:

• Esc in the control pane first ends the whole tmux session (tmux kill-session, closing both k9s panes as well) and then moves the Go tool's screen stack one level up: namespace selection -> team selection -> context selection.
• Tab in the control pane switches the context pair according to the context-pair pattern (see 3.6) for both status panes simultaneously; the namespace stays the same.

3.2 Namespace grouping via labels

• Display all currently assigned labels per namespace: kubectl get ns --show-labels.
• Query all distinct values of an arbitrary label key (including keys with a dot/slash) via bracket notation in JSONPath. Example with a generic placeholder key <team-label-key>:

  kubectl get ns -o jsonpath='{range .items[*]}{.metadata.labels["<team-label-key>"]}{"\n"}{end}' | sort -u
  

• The actual label key is project-specific and set via the configuration file (see 3.6), not hardcoded.
• Namespace labeling is a prerequisite (one-time setup outside the tool).

3.3 Layout: 3-panel view (core design change vs. earlier drafts)

Once start navigation is complete, the tool opens a tmux session with three panes, started with a single command:

+--------------------------------------------------+
|  Pane 0 (top): Control pane                      |
|  -> runs the kctl-tui binary in "panel" mode      |
|  -> menu: Redeploy, secrets diff                  |
+--------------------------------------------------+
|  Pane 1 (middle): k9s --context <context-a> -n <ns>|
+--------------------------------------------------+
|  Pane 2 (bottom): k9s --context <context-b> -n <ns>|
+--------------------------------------------------+

Important: a separate "status" menu item in the control pane is not needed — status is continuously visible via the two k9s panes for as long as the session runs. The control pane only contains the actions k9s does not cover: redeploy and secrets diff.

Example startup command (generic placeholders):

tmux new-session -d -s kctl \
  "kctl-tui panel --ctx=$CTX_A --ns=$NS --team=$TEAM" \; \
  split-window -v "k9s --context $CTX_A -n $NS" \; \
  split-window -v "k9s --context $CTX_B -n $NS" \; \
  select-layout main-horizontal \; \
  attach -t kctl

Switching between panes: Ctrl-b + arrow key, or Ctrl-b o.

3.4 Redeploy (rollout restart) — in the control pane

• List all deployments in the currently selected namespace for selection (kubectl -n <ns> get deploy).
• Confirmation step before execution.
• Execute kubectl -n <ns> rollout restart deploy/<name> followed by kubectl -n <ns> rollout status deploy/<name>.
• The result is immediately visible in the status panes below (pods get recreated) — no separate status feedback channel needed in the tool itself.

3.5 AWS Secrets Manager <-> Kubernetes Secret diff — in the control pane

1. Load the secret from AWS Secrets Manager: aws secretsmanager get-secret-value --secret-id <secret-id> --region <region> --query SecretString --output text.
2. Show the contained keys for selection.
3. Load the matching Kubernetes secret field: kubectl -n <ns> get secret <secret-name> -o jsonpath='{.data.<field>}', base64-decode it.
4. Compare the values (identical / different).
5. On mismatch, optionally request a force-sync: kubectl -n <ns> annotate externalsecret <name> force-sync=<unix-timestamp> --overwrite.

All names (secret ID, secret name, field name, ExternalSecret name) are asked for interactively at runtime, never hardcoded in the tool.

3.6 Context-pair pattern (configurable) — drives both status panes at once

Requirement: the Tab switch in the control pane must switch both status panes below it, not just an internal state.

Configuration format (e.g. ~/.kctl-tui/config.yaml), purely illustrative with generic placeholders:

context_pairs:
  - name: "environment-pair-1"
    contexts: ["<context-a1>", "<context-a2>"]
  - name: "environment-pair-2"
    contexts: ["<context-b1>", "<context-b2>"]

team_label_key: "<organization>/<label-name>"

Behavior on Tab in the control pane:

1. Determine the current context pair from the configuration.
2. Restart both k9s panes via tmux respawn-pane -k -t kctl:0.1 "k9s --context <newA> -n <ns>" and ... kctl:0.2 ... (namespace stays the same).
3. If the current context is in no configured list: show a hint in the control pane instead of an error.
4. No action outside this configuration — no error, only a hint.

Platform limitation on Windows without WSL: respawn-pane/ kill-session are tmux-specific. Windows Terminal (wt.exe) offers no equivalent scripting to replace panes or end the session from inside a pane. On plain Windows (without WSL), only a simplified flow is possible: k9s panes are closed manually (q, then Ctrl+Shift+W); Tab switching and automatic session termination are unavailable there. This limitation is the main reason the primary target system is set to Linux/WSL.

4. Non-functional requirements

• Primary platform Linux/WSL, secondary native Windows with reduced functionality.
• Single-binary distribution without external runtime dependency (Go provides this natively).
• External dependencies: kubectl mandatory; tmux, k9s, aws-cli depending on the action used.
• Low startup time, noticeably faster than the current kubens experience.
• No destructive actions without confirmation (redeploy, force-sync).
• No project- or company-specific names (contexts, namespaces, label keys, secret names) in code or example files — everything is sourced via configuration or interactive input at runtime.

5. Technology decision: Go + Bubble Tea

Rationale:

• The Kubernetes tooling ecosystem (kubectl, k9s, client-go) is itself written in Go — enabling direct API access instead of pure shell calls in the future.
• Bubble Tea (Charm) is specifically built for hierarchical, keyboard-driven TUIs with a screen stack, same look/feel as k9s.
• Static, small binary without runtime dependency; fast cross-compilation (GOOS=linux/windows).
• Both Go and .NET are fundamentally cross-platform; since the real target is Linux/WSL anyway (due to the split-view requirement), .NET's main advantage (one runtime for both worlds in a single step) no longer applies, so the choice is free to fall on the technically closest ecosystem.

Rejected options (see discussion history):

• Python + Textual: good prototype, but requires an additional runtime, no single binary without extra effort (PyInstaller).
• .NET + Terminal.Gui: technically equivalent, but larger binary, no compelling advantage anymore with a Linux-only target.
• Rust + Ratatui: excellent TUI library, but a steeper learning curve without a clear extra benefit over Go for this project.

6. Already solved by standard tooling (no custom build needed)

• Generic fuzzy selection of context/namespace: kubectx + kubens + fzf.
• Ad-hoc actions directly from k9s with the current context/namespace/ resource name: k9s plugins (~/.k9s/plugin.yml).
• Split panes themselves: tmux (Linux/WSL) or native Windows Terminal panes (wt.exe split-pane) — no custom multiplexer code needed, the tool only orchestrates existing tools.

7. Environment prerequisites (WSL-specific, from troubleshooting)

• kubectx/kubens incompletely installed: Some Linux distro packages for kubectx only ship the kubectx binary without kubens. Fix: install via the distribution's package manager properly, or manually symlink both scripts from the official project repository.
• "kubeconfig file not found" in WSL: The kubeconfig often only exists in the Windows user profile; WSL has its own, separate home directory. Fix via symlink:

  mkdir -p ~/.kube
  ln -s /mnt/c/Users/<windows-username>/.kube/config ~/.kube/config
  

  or via the KUBECONFIG environment variable pointing to the same Windows path.
• These fixes are a prerequisite before the tool can be meaningfully tested, since it builds directly on kubectl config.

8. Open items / out of scope (v1)

• No automatic label setup for namespaces (migration is a separate, one-time task).
• Split view v1 fixed at 2 status panes + 1 control pane (3 panes total).
• No RBAC/permission checks before executing sensitive actions — the tool assumes existing kubectl permissions.
• Configuration file format (config.yaml) is a proposal, not finally agreed; concrete label keys, context names, and namespace names are project-specific and belong exclusively in the user's local, unversioned configuration, not in this document or the source code.
• Native Windows (without WSL) remains a secondary platform with manual pane handling instead of an automated tmux lifecycle.