How derailed/k9s works
1. What this repo is
- K9s is a Go-based terminal UI for managing Kubernetes clusters.
- The runtime is a single interactive CLI process; there is no server component. It talks directly to the Kubernetes API and related cluster endpoints, then renders everything in the terminal.
2. Startup and CLI boundary
- main.go plus cmd/ provide the executable entrypoint, version/info commands, and top-level flags.
- Startup resolves the active kubeconfig/context, loads K9s config, then boots the terminal app and initial view.
3. Configuration as a first-class subsystem
- internal/config/ owns all YAML-based configuration: global app config, context/cluster config, aliases, hotkeys, jumps, plugins, views, skins, logger settings, thresholds, and feature gates.
- A lot of behavior is driven by files under XDG locations, so the runtime is highly data-driven and customizable per cluster/context.
4. Kubernetes access and cluster state
- internal/client/ wraps Kubernetes client interaction, kubeconfig handling, REST mapping/GVR resolution, metrics access, and context switching.
- This layer is the main boundary to the external world: the Kubernetes API server, metrics API, and the current cluster/context identity.
5. Watch/cache pipeline
- internal/watch/ manages resource watches and forwards update events into the rest of the app.
- K9s depends on continuous watch streams so views stay live as cluster objects change, rather than doing one-shot list calls only.
6. Data access and resource normalization
- internal/dao/ contains resource-specific data access objects for pods, deployments, services, nodes, namespaces, RBAC, CRDs, secrets, logs, port-forwarding, and more.
- This layer turns Kubernetes objects and API responses into normalized, view-friendly structures. It also hosts operations such as describe, delete, patch, restart, drain, and log retrieval.
7. Rendering pipeline
- internal/render/ converts DAO output into tabular rows, columns, details, YAML, and specialized summaries for each resource type.
- internal/model/ and internal/model1/ hold the display models: tables, rows, histories, logs, summaries, text blocks, and delta/state tracking used by the UI.
- Conceptually the path is: Kubernetes object → DAO normalization → render model → terminal table/detail view.
8. Terminal UI framework
- internal/ui/ provides the generic terminal widgets: tables, menus, prompts, dialogs, breadcrumbs, pages, flashes, tree views, splash screens, and selection workflows.
- This is the presentation layer independent of specific Kubernetes resources.
9. Resource-specific application views
- internal/view/ is the main “controller” layer for K9s features. It binds user actions and keybindings to resource-specific behavior.
- It includes views for pods, nodes, workloads, RBAC, services, logs, events, config maps, secrets, CRDs, namespaces, port-forwards, benchmarks, YAML, help, and command execution.
- It also contains extensibility hooks such as command interpreter support, clipboard integration, custom jumps, extenders, and screen dumps.
10. Specialized feature subsystems
- internal/xray/ builds relationship/ownership graphs for resources like pods, deployments, statefulsets, daemonsets, services, nodes, and namespaces.
- internal/vul/ handles image vulnerability scanning and scoring.
- internal/health/ computes health/status checks.
- internal/port/ models port-forward state and tunneling.
- internal/tchart/ supports charts/gauges/sparklines used by monitoring-style views.
- internal/perf/ and the benchmark-related code support HTTP benchmarking of port-forwards and services.
11. Extensibility and external command execution
- plugins/ contains YAML-defined plugins that execute external commands, often shelling out to tools like kubectl, log tailers, debuggers, or cluster utilities.
- jumps/ and the jump config support resource-to-resource navigation rules, especially for CRDs.
- skins/ define terminal styling, while assets/ contains UI/media assets and sample material.
12. Persistence and local artifacts
- K9s stores runtime artifacts locally: logs, screen dumps, benchmark results, cluster/context files, and custom config files.
- The state is partitioned by cluster/context, which matters for architecture because many behaviors are scoped to a specific Kubernetes environment rather than global app state.
13. Operational model
- The app is read-heavy and watch-driven, but it also supports targeted mutating operations: edit, delete, restart, cordon/uncordon, drain, rollout/rollback, shell/exec, port-forward, and plugin-triggered actions.
- Read-only mode and RBAC constraints are enforced as part of the user experience, so permissions directly shape what actions and views are available.
Main entry points: app.go Views · config.go Config · main.go Main · client.go Client
Components 20
Entry & startup
Executable boundary and initial bootstrapping.
Core runtime
Configuration, Kubernetes access, watch pipeline, and normalization.
- Config · App, context, hotkey, view, skin, and plugin configuration.
internal/config/config.go - Client · Kubernetes API, kubeconfig, metrics, and context switching.
internal/client/client.go - Watch · Resource watch streams and event forwarding.
internal/watch/factory.go - DAO · Resource-specific access, normalization, and mutating operations.
internal/dao/registry.go - Render · Transforms normalized resources into rows, tables, YAML, and summaries.
internal/render/base.go - Models · UI-facing tables, rows, history, logs, and delta/state tracking.
internal/model/table.go - Row model · Lower-level row, header, and delta table data structures.
internal/model1/table_data.go
Terminal UI
Presentation framework and resource controllers.
Specialized features
Auxiliary subsystems for graphs, scans, health, ports, and benchmarking.
- Xray · Ownership and relationship graphs for Kubernetes resources.
internal/xray/generic.go - Vuln scan · Image vulnerability scanning and scoring.
internal/vul/scan.go - Health · Resource health and status evaluation.
internal/health/check.go - Port forward · Port-forward state and tunnel modeling.
internal/port/tunnel.go - Benchmark · HTTP benchmarking support for services and forwards.
internal/perf/benchmark.go
Extensibility
Plugins, jumps, skins, and bundled assets.
Connections 25
- Main → CLI: starts with · Entrypoint dispatches CLI handling.
- Main → Config: loads · Bootstraps runtime configuration and context.
- Main → Client: connects · Initializes Kubernetes access for the active cluster.
- Main → UI: boots · Starts the terminal application.
- CLI → Config: flags · Command-line flags influence configuration loading.
- Config → Client: context · Config drives kubecontext and cluster-scoped state.
- Client → Watch: streams · Client-backed watches feed live updates.
- Watch → DAO: events · Watch events are consumed by resource data access.
- Client → DAO: API · DAO layer uses Kubernetes API access and mappings.
- DAO → Render: normalizes · Resource objects are converted to view-friendly output.
- Render → Models: builds · Rendering produces UI-oriented models.
- Models → Row model: backs · Higher-level models sit on row/table data structures.
- Row model → UI: feeds · Row and table data drive terminal widgets.
- UI → Views: hosts · Generic widgets are orchestrated by resource views.
- Views → DAO: actions · Views trigger read and mutating resource operations.
- Views → Xray: graph · Some views render ownership and dependency graphs.
- Views → Vuln scan: scan · Image scanning is exposed through view flows.
- Views → Health: checks · Health computations surface in resource views.
- Views → Port forward: forwards · Port-forward workflows are managed from views.
- Views → Benchmark: benchmarks · Benchmarking flows are launched from the UI.
- Views → Plugins: extends · External command plugins are invoked from views.
- Views → Jumps: navigates · Jump rules connect related resources.
- Config → Skins: themes · Skin selection is configuration-driven.
- Config → Plugins: loads · Plugin definitions are config-backed.
- UI → Assets: draws from · UI uses bundled assets and sample material.