github vladimirvivien/ktop v0.7.1
Version 0.7.1

one hour ago

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: ktop previously 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.Options in application/headless/app.go) implementing application.Runner without terminal screen dependencies, backed by collector.Collector and collector.K8sSnapshotProvider (collector/collector.go, collector/k8s_provider.go). Added synchronous informer startup (Controller.StartInformers in k8s/client_controller.go), exported Controller.BuildClusterSummary (k8s/summary_controller.go), and added scrape-cycle synchronization (Controller.WaitForCycles in prom/controller.go and PromMetricsSource.WaitForWarmup in metrics/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 one collector.Aggregate document (metadata, cluster, summary, health_score_stats, nodes, pods), and exit. Timed runs (-d > 0) sample every -i (--interval, default 5s), include the ordered samples slice in -o json, and handle SIGINT/SIGTERM cleanly by flushing all samples collected prior to cancellation. When --prometheus-scrape-interval is not explicitly set in --noui mode, single-shot runs tune the internal scrape cadence to 1500ms (or -i when 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.JSONLFormatter in output/formatter.go, output/json.go, output/jsonl.go). JSONFormatter encodes a single indented collector.Aggregate document upon completion, while JSONLFormatter encodes one minified snapshot.Snapshot line per interval tick with HTML escaping disabled and immediate buffer flushing.
  • Impact & Behavioral Notes: stdout receives strictly valid JSON or JSONL with canonical numeric units (millis for CPU, bytes for memory and storage, and 0.0–100.0 percentages for PSI stall and CFS throttling).

2. Cluster Health Score & Window Aggregations

OOMKilled and CrashLoopBackOff Detection and HealthScoreStats

  • Problem / Context: Pods in Running or Pending phase with containers restarting due to OOMKilled or CrashLoopBackOff were 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") to model.ClusterSummary (views/model/summary_model.go) and snapshot.SummaryData (internal/snapshot/snapshot.go, internal/snapshot/builder.go). Updated Controller.BuildClusterSummary (k8s/summary_controller.go) to inspect both InitContainerStatuses and ContainerStatuses for OOMKilled (State.Terminated and LastTerminationState.Terminated) and CrashLoopBackOff (State.Waiting), and updated model.CalculateHealthScore to apply the -15 pod-health deduction when FailedPods > 0 || OOMKillCount > 0 || CrashLoopPods > 0. Added collector.HealthScoreStats (min, max, avg, latest) to collector.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 --noui JSON/JSONL snapshots reflect OOMKilled and CrashLoopBackOff containers in health_score, while downstream scripts express custom pass/fail thresholds against summary.health_score and health_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 stderr progress output and structured log destinations.
  • Implementation Details: Added --noui, -d/--duration, -i/--interval, -o/--output, --quiet, and --log (file or stderr) in cmd/ktop.go (NewKtopCmd), along with logging.Validate (internal/logging/logger.go). Added cmd/exitcode.go defining ExitOK (0), ExitGeneralError (1), ExitInvalidFlags (2), ExitK8sConnectError (3), ExitMetricsUnavailable (4), and ExitCollectionTimeout (5), mapped via cmd.ExitError, cmd.WrapExitError, and cmd.ExitCode in main.go.
  • Impact & Behavioral Notes: Invalid CLI flags, negative --duration, non-positive --interval, unsupported --output formats, or unknown --log destinations fail before cluster connection with exit code 2. API connection or RBAC preflight failures return 3; unavailable explicitly requested metrics sources (--metrics-source=prometheus or --metrics-source=metrics-server) return 4; informer sync or warmup timeouts (--request-timeout) return 5.

Upgrade & Compatibility Notes

  • Backward Compatibility: Fully backward compatible with existing interactive ktop CLI invocations, kubectl ktop plugin usage, kubeconfig setups, and ~/.ktop/config.yaml files. Running ktop without --noui launches 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 than 1, and clusters with active OOMKilled or CrashLoopBackOff containers now include the -15 deduction in health_score.

Workspace / Repository Metrics

 33 files changed, 2841 insertions(+), 253 deletions(-)

Don't miss a new ktop release

NewReleases is sending notifications on new releases.