ktop Release v0.7.1
ktop v0.7.1 introduces scriptable non-interactive (--noui) execution for CI/CD gates, cron jobs, and telemetry pipelines, incorporates OOMKilled and CrashLoopBackOff container states into the composite 0–100 cluster health score alongside window-level health_score_stats, and defines structured operational exit codes (0–5) and log sink routing (--log).
Passing --noui bypasses terminal UI allocation, synchronizes Kubernetes informers and initial Prometheus scrape cycles, and writes indented single-document JSON (-o json) or line-delimited streaming snapshots (-o jsonl) to stdout while keeping readiness diagnostics on stderr (or suppressed with --quiet) and structured logs in ~/.ktop/ktop.log.
Detailed Changes by Category
1. Non-Interactive (--noui) Collection & Output Pipeline
Headless Application Runner and Synchronous Snapshot Collector
- Problem / Context:
ktoppreviously required an interactive TTY (tview/tcell) to observe cluster state and metrics, preventing automated scripts, CI deployment gates, and headless jobs from capturing structured cluster snapshots. - Implementation Details: Added package
application/headless(headless.NewRunner,headless.App,headless.Optionsinapplication/headless/app.go) implementingapplication.Runnerwithout terminal screen dependencies, backed bycollector.Collectorandcollector.K8sSnapshotProvider(collector/collector.go,collector/k8s_provider.go). Added synchronous informer startup (Controller.StartInformersink8s/client_controller.go), exportedController.BuildClusterSummary(k8s/summary_controller.go), and added scrape-cycle synchronization (Controller.WaitForCyclesinprom/controller.goandPromMetricsSource.WaitForWarmupinmetrics/prom/prom_source.go) so Prometheus counter rates warm up across two completed scrape cycles before sampling. - Impact & Behavioral Notes: Single-shot runs (
-d 0s, default) wait for core informer cache sync and metrics warmup, emit onecollector.Aggregatedocument (metadata,cluster,summary,health_score_stats,nodes,pods), and exit. Timed runs (-d > 0) sample every-i(--interval, default5s), include the orderedsamplesslice in-o json, and handleSIGINT/SIGTERMcleanly by flushing all samples collected prior to cancellation. When--prometheus-scrape-intervalis not explicitly set in--nouimode, single-shot runs tune the internal scrape cadence to1500ms(or-iwhen smaller) so rate metrics warm up promptly.
JSON and Streaming JSONL Output Formatters
- Problem / Context: Automation consumers need both complete end-of-window reports for post-deployment assertions and real-time line-delimited streams for continuous pipelines.
- Implementation Details: Added package
output(output.Formatter,output.NewFormatter,output.JSONFormatter,output.JSONLFormatterinoutput/formatter.go,output/json.go,output/jsonl.go).JSONFormatterencodes a single indentedcollector.Aggregatedocument upon completion, whileJSONLFormatterencodes one minifiedsnapshot.Snapshotline per interval tick with HTML escaping disabled and immediate buffer flushing. - Impact & Behavioral Notes:
stdoutreceives strictly valid JSON or JSONL with canonical numeric units (millisfor CPU,bytesfor memory and storage, and0.0–100.0percentages for PSI stall and CFS throttling).
2. Cluster Health Score & Window Aggregations
OOMKilled and CrashLoopBackOff Detection and HealthScoreStats
- Problem / Context: Pods in
RunningorPendingphase with containers restarting due toOOMKilledorCrashLoopBackOffwere not reflected in the cluster summary's pod-failure health score deduction, and multi-sample runs lacked window-level health score summaries. - Implementation Details: Added
CrashLoopPods(json:"crashloop_pods") tomodel.ClusterSummary(views/model/summary_model.go) andsnapshot.SummaryData(internal/snapshot/snapshot.go,internal/snapshot/builder.go). UpdatedController.BuildClusterSummary(k8s/summary_controller.go) to inspect bothInitContainerStatusesandContainerStatusesforOOMKilled(State.TerminatedandLastTerminationState.Terminated) andCrashLoopBackOff(State.Waiting), and updatedmodel.CalculateHealthScoreto apply the-15pod-health deduction whenFailedPods > 0 || OOMKillCount > 0 || CrashLoopPods > 0. Addedcollector.HealthScoreStats(min,max,avg,latest) tocollector.Aggregate. - APIs / Signatures:
# Capture a single JSON snapshot ktop --noui | jq . # Gate a CI pipeline on point-in-time health_score or OOM/crashloop counts ktop --noui --quiet | jq -e '.summary.health_score >= 80 and .summary.oom_kill_count == 0 and .summary.crashloop_pods == 0' # Gate on sustained window statistics over a 30s soak period ktop --noui -d 30s -i 5s --quiet | jq -e '.health_score_stats.min >= 70 and .health_score_stats.avg >= 85' # Stream minified JSONL snapshots every 5s ktop --noui -d 5m -i 5s -o jsonl --quiet
- Impact & Behavioral Notes: Both the interactive TUI Cluster Summary header and
--nouiJSON/JSONL snapshots reflectOOMKilledandCrashLoopBackOffcontainers inhealth_score, while downstream scripts express custom pass/fail thresholds againstsummary.health_scoreandhealth_score_stats.
3. CLI Flags, Logging Isolation & Operational Exit Codes
Headless Flags, --log Destination Control, and Exit Codes 0–5
- Problem / Context: Automated callers need deterministic process exit codes to separate invalid flags from cluster connectivity, missing metrics backends, and readiness timeouts, as well as explicit control over
stderrprogress output and structured log destinations. - Implementation Details: Added
--noui,-d/--duration,-i/--interval,-o/--output,--quiet, and--log(fileorstderr) incmd/ktop.go(NewKtopCmd), along withlogging.Validate(internal/logging/logger.go). Addedcmd/exitcode.godefiningExitOK(0),ExitGeneralError(1),ExitInvalidFlags(2),ExitK8sConnectError(3),ExitMetricsUnavailable(4), andExitCollectionTimeout(5), mapped viacmd.ExitError,cmd.WrapExitError, andcmd.ExitCodeinmain.go. - Impact & Behavioral Notes: Invalid CLI flags, negative
--duration, non-positive--interval, unsupported--outputformats, or unknown--logdestinations fail before cluster connection with exit code2. API connection or RBAC preflight failures return3; unavailable explicitly requested metrics sources (--metrics-source=prometheusor--metrics-source=metrics-server) return4; informer sync or warmup timeouts (--request-timeout) return5.
Upgrade & Compatibility Notes
- Backward Compatibility: Fully backward compatible with existing interactive
ktopCLI invocations,kubectl ktopplugin usage, kubeconfig setups, and~/.ktop/config.yamlfiles. Runningktopwithout--nouilaunches the interactive terminal UI unchanged. - Deprecations & Retractions: None.
- Migration Actions: None required. Note that CLI flag validation errors now exit with status code
2(ExitInvalidFlags) rather than1, and clusters with activeOOMKilledorCrashLoopBackOffcontainers now include the-15deduction inhealth_score.
Workspace / Repository Metrics
33 files changed, 2841 insertions(+), 253 deletions(-)