# derailed/k9s architecture

> Architecture diagram of the GitHub repository derailed/k9s, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/derailed/k9s
- Repository: https://github.com/derailed/k9s

## Overview

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: [`internal/view/app.go`](https://github.com/derailed/k9s/blob/master/internal/view/app.go) (Views), [`internal/config/config.go`](https://github.com/derailed/k9s/blob/master/internal/config/config.go) (Config), [`main.go`](https://github.com/derailed/k9s/blob/master/main.go) (Main), [`internal/client/client.go`](https://github.com/derailed/k9s/blob/master/internal/client/client.go) (Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_entry["Entry & startup"]
  node_n_main(("Main<br/>entrypoint<br/>[main.go]"))
  node_n_cmd["CLI<br/>commands<br/>[root.go]"]
end

subgraph group_g_core["Core runtime"]
  node_n_config["Config<br/>[config.go]"]
  node_n_client["Client<br/>kube access<br/>[client.go]"]
  node_n_watch["Watch<br/>event stream<br/>[factory.go]"]
  node_n_dao["DAO<br/>resource access<br/>[registry.go]"]
  node_n_render["Render<br/>view model<br/>[base.go]"]
  node_n_model["Models<br/>table/log state<br/>[table.go]"]
  node_n_model1["Row model<br/>table rows<br/>[table_data.go]"]
end

subgraph group_g_ui["Terminal UI"]
  node_n_ui["UI<br/>widgets<br/>[app.go]"]
  node_n_view["Views<br/>controllers<br/>[app.go]"]
end

subgraph group_g_features["Specialized features"]
  node_n_xray{{"Xray<br/>relationship graph<br/>[generic.go]"}}
  node_n_vul{{"Vuln scan<br/>security scan<br/>[scan.go]"}}
  node_n_health{{"Health<br/>status checks<br/>[check.go]"}}
  node_n_port{{"Port forward<br/>tunneling<br/>[tunnel.go]"}}
  node_n_perf{{"Benchmark<br/>perf<br/>[benchmark.go]"}}
end

subgraph group_g_ext["Extensibility"]
  node_n_plugins["Plugins<br/>external commands<br/>[README.md]"]
  node_n_jumps["Jumps<br/>navigation rules<br/>[certificates.yaml]"]
  node_n_skins["Skins<br/>themes<br/>[stock.yaml]"]
  node_n_assets["Assets<br/>bundled media"]
end

node_n_main -->|"starts with"| node_n_cmd
node_n_main -->|"loads"| node_n_config
node_n_main -->|"connects"| node_n_client
node_n_main -->|"boots"| node_n_ui
node_n_cmd -->|"flags"| node_n_config
node_n_config -->|"context"| node_n_client
node_n_client -->|"streams"| node_n_watch
node_n_watch -->|"events"| node_n_dao
node_n_client -->|"API"| node_n_dao
node_n_dao -->|"normalizes"| node_n_render
node_n_render -->|"builds"| node_n_model
node_n_model -->|"backs"| node_n_model1
node_n_model1 -->|"feeds"| node_n_ui
node_n_ui -->|"hosts"| node_n_view
node_n_view -->|"actions"| node_n_dao
node_n_view -->|"graph"| node_n_xray
node_n_view -->|"scan"| node_n_vul
node_n_view -->|"checks"| node_n_health
node_n_view -->|"forwards"| node_n_port
node_n_view -->|"benchmarks"| node_n_perf
node_n_view -->|"extends"| node_n_plugins
node_n_view -->|"navigates"| node_n_jumps
node_n_config -->|"themes"| node_n_skins
node_n_config -->|"loads"| node_n_plugins
node_n_ui -->|"draws from"| node_n_assets

click node_n_main "https://github.com/derailed/k9s/blob/master/main.go"
click node_n_cmd "https://github.com/derailed/k9s/blob/master/cmd/root.go"
click node_n_config "https://github.com/derailed/k9s/blob/master/internal/config/config.go"
click node_n_client "https://github.com/derailed/k9s/blob/master/internal/client/client.go"
click node_n_watch "https://github.com/derailed/k9s/blob/master/internal/watch/factory.go"
click node_n_dao "https://github.com/derailed/k9s/blob/master/internal/dao/registry.go"
click node_n_render "https://github.com/derailed/k9s/blob/master/internal/render/base.go"
click node_n_model "https://github.com/derailed/k9s/blob/master/internal/model/table.go"
click node_n_model1 "https://github.com/derailed/k9s/blob/master/internal/model1/table_data.go"
click node_n_ui "https://github.com/derailed/k9s/blob/master/internal/ui/app.go"
click node_n_view "https://github.com/derailed/k9s/blob/master/internal/view/app.go"
click node_n_xray "https://github.com/derailed/k9s/blob/master/internal/xray/generic.go"
click node_n_vul "https://github.com/derailed/k9s/blob/master/internal/vul/scan.go"
click node_n_health "https://github.com/derailed/k9s/blob/master/internal/health/check.go"
click node_n_port "https://github.com/derailed/k9s/blob/master/internal/port/tunnel.go"
click node_n_perf "https://github.com/derailed/k9s/blob/master/internal/perf/benchmark.go"
click node_n_plugins "https://github.com/derailed/k9s/blob/master/plugins/README.md"
click node_n_jumps "https://github.com/derailed/k9s/blob/master/jumps/certificates.yaml"
click node_n_skins "https://github.com/derailed/k9s/blob/master/skins/stock.yaml"
click node_n_assets "https://github.com/derailed/k9s/tree/master/assets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main,node_n_cmd toneBlue
class node_n_config,node_n_client,node_n_watch,node_n_dao,node_n_render,node_n_model,node_n_model1 toneAmber
class node_n_ui,node_n_view toneMint
class node_n_xray,node_n_vul,node_n_health,node_n_port,node_n_perf toneRose
class node_n_plugins,node_n_jumps,node_n_skins,node_n_assets toneIndigo
```

## Components

### Entry & startup

Executable boundary and initial bootstrapping.

- [Main](https://github.com/derailed/k9s/blob/master/main.go): entrypoint · Process entry and top-level startup. · `main.go`
- [CLI](https://github.com/derailed/k9s/blob/master/cmd/root.go): commands · Version/info commands and root flags. · `cmd/root.go`

### Core runtime

Configuration, Kubernetes access, watch pipeline, and normalization.

- [Config](https://github.com/derailed/k9s/blob/master/internal/config/config.go): yaml config · App, context, hotkey, view, skin, and plugin configuration. · `internal/config/config.go`
- [Client](https://github.com/derailed/k9s/blob/master/internal/client/client.go): kube access · Kubernetes API, kubeconfig, metrics, and context switching. · `internal/client/client.go`
- [Watch](https://github.com/derailed/k9s/blob/master/internal/watch/factory.go): event stream · Resource watch streams and event forwarding. · `internal/watch/factory.go`
- [DAO](https://github.com/derailed/k9s/blob/master/internal/dao/registry.go): resource access · Resource-specific access, normalization, and mutating operations. · `internal/dao/registry.go`
- [Render](https://github.com/derailed/k9s/blob/master/internal/render/base.go): view model · Transforms normalized resources into rows, tables, YAML, and summaries. · `internal/render/base.go`
- [Models](https://github.com/derailed/k9s/blob/master/internal/model/table.go): table/log state · UI-facing tables, rows, history, logs, and delta/state tracking. · `internal/model/table.go`
- [Row model](https://github.com/derailed/k9s/blob/master/internal/model1/table_data.go): table rows · Lower-level row, header, and delta table data structures. · `internal/model1/table_data.go`

### Terminal UI

Presentation framework and resource controllers.

- [UI](https://github.com/derailed/k9s/blob/master/internal/ui/app.go): widgets · Generic terminal widgets, dialogs, tables, pages, and prompts. · `internal/ui/app.go`
- [Views](https://github.com/derailed/k9s/blob/master/internal/view/app.go): controllers · Resource views, keybindings, actions, and command workflows. · `internal/view/app.go`

### Specialized features

Auxiliary subsystems for graphs, scans, health, ports, and benchmarking.

- [Xray](https://github.com/derailed/k9s/blob/master/internal/xray/generic.go): relationship graph · Ownership and relationship graphs for Kubernetes resources. · `internal/xray/generic.go`
- [Vuln scan](https://github.com/derailed/k9s/blob/master/internal/vul/scan.go): security scan · Image vulnerability scanning and scoring. · `internal/vul/scan.go`
- [Health](https://github.com/derailed/k9s/blob/master/internal/health/check.go): status checks · Resource health and status evaluation. · `internal/health/check.go`
- [Port forward](https://github.com/derailed/k9s/blob/master/internal/port/tunnel.go): tunneling · Port-forward state and tunnel modeling. · `internal/port/tunnel.go`
- [Benchmark](https://github.com/derailed/k9s/blob/master/internal/perf/benchmark.go): perf · HTTP benchmarking support for services and forwards. · `internal/perf/benchmark.go`

### Extensibility

Plugins, jumps, skins, and bundled assets.

- [Plugins](https://github.com/derailed/k9s/blob/master/plugins/README.md): external commands · YAML-defined external command integrations. · `plugins/README.md`
- [Jumps](https://github.com/derailed/k9s/blob/master/jumps/certificates.yaml): navigation rules · Resource-to-resource navigation mappings. · `jumps/certificates.yaml`
- [Skins](https://github.com/derailed/k9s/blob/master/skins/stock.yaml): themes · Terminal styling and color themes. · `skins/stock.yaml`
- [Assets](https://github.com/derailed/k9s/tree/master/assets): bundled media · Static UI assets and sample material. · `assets`

## Connections

- 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.
