kube-foresight 0.3.1

Predictive Resource Optimizer for Kubernetes — identifies over-provisioned deployments and generates right-sizing patches

kube-foresight

Right-size your Kubernetes deployments, forecast resource trends, and estimate the multi-cloud cost impact — in one tool, with kubectl-ready patches.

What it does

Most teams over-provision Kubernetes by 40–70% out of fear of outages — and fixing it usually means stitching several tools together: one to recommend new resources, another to apply them, another to watch for future breaches, another to price the change.

kube-foresight runs that whole loop in a single CLI and dashboard:

recommendation → kubectl-ready patch → breach forecast → multi-cloud cost

It reads live usage from your Metrics API or Prometheus, recommends right-sized requests and limits, emits a patch you review and kubectl apply, predicts when usage will breach current limits, and prices the reclaimed capacity across AWS / GCP / Azure.

Status: Alpha — under active development. Analysis is read-only (the CLI never changes your cluster), so it's safe to evaluate against real workloads; validate recommendations before applying them at scale. Production deployment reports, issues, and PRs especially welcome.

Install

pip install "kube-foresight[dashboard]"   # Python 3.10+

Prefer a container? See Deployment.

Use it on your cluster

kube-foresight reads usage from the Kubernetes Metrics API (via metrics-server) or Prometheus. It never edits workloads itself — it writes patch files you apply on your own terms.

# 1. Find over-provisioned deployments
kube-foresight analyze   -n production --mode k8s
kube-foresight recommend -n production --mode prometheus -p http://prometheus:9090

# 2. Generate kubectl-ready patches — review, then apply
kube-foresight patch -n production --mode k8s -o ./patches
kubectl apply -f ./patches/api-gateway-patch.yaml

# 3. Forecast when usage will breach current limits
kube-foresight forecast -n production --mode k8s

Preview without a cluster

See the full pipeline and dashboard against representative sample workloads — no cluster, RBAC, or metrics-server required:

kube-foresight demo                 # full pipeline, sample data
kube-foresight dashboard --demo     # web UI at http://localhost:8080

Why trust the recommendations

Right-sizing is only useful if it doesn't cause the outages teams over-provision to avoid. kube-foresight is built defensively:

• It never auto-applies. It recommends and generates patches; every change to your cluster is one you trigger (kubectl apply, or the dashboard's apply action).
• Sizes on real demand. Recommendations use p95 / p99 of observed usage with configurable headroom, computed on raw data so demand spikes aren't discarded — under-provisioning is the dangerous error, so it errs toward the tail.
• Per-resource. CPU and memory are sized independently; a CPU-wasteful workload pinned at its memory limit gets its CPU cut without touching memory.
• HPA-aware. It refuses to recommend changes that would fight a HorizontalPodAutoscaler.
• Backtested. Recommendations are validated against a public production trace (Alibaba 2018) with a held-out train/test split. The methodology and results are in benchmarks/.

What's in the box

• Three collectors — Kubernetes Metrics API, Prometheus, or mock (demo / CI)
• Statistical right-sizing — p95 / p99 / max strategies (p99 default), CPU and memory sized independently with configurable headroom
• Forecasting — linear-regression breach-time prediction with risk classification
• Multi-cloud cost estimation — prices reclaimable CPU/memory at approximate on-demand rates for AWS / GCP / Azure
• Patch generator — strategic-merge YAML you can kubectl apply
• Web dashboard — FastAPI + HTMX + Chart.js (overview, recommendations, cost comparison)
• Production plumbing — Dockerfile, Helm chart, health probes, structured JSON logs, optional Slack alerts

How costs are calculated: figures reflect reclaimable capacity — the difference between current and recommended requests, priced at approximate blended on-demand rates for the selected provider. Translating reclaimed capacity into billing changes depends on node consolidation by the cluster autoscaler; pair with Kubecost/OpenCost for allocation-accurate spend.

Where it fits

Several tools cover individual pieces of this well:

• KRR — Prometheus-based right-sizing recommendations.
• Goldilocks — surfaces VPA recommendations across a cluster.
• VPA — in-cluster vertical autoscaling that can apply changes automatically.
• Kubecost / OpenCost — allocation-accurate cost monitoring and spend reporting.

kube-foresight's niche is bringing right-sizing, breach forecasting, kubectl patch output, and side-by-side multi-cloud pricing into one workflow. If KRR already covers your recommendations and Kubecost your spend, you may not need it — it's for teams who'd rather run one loop than wire several tools together.

CLI reference

Command	Purpose
demo	Full pipeline with sample data — no cluster required
analyze	Identify over-provisioned deployments
collect	Snapshot metrics into SQLite for trend analysis
recommend	Right-sizing recommendations + cost estimates
patch	Generate kubectl-applyable YAML patches
forecast	Predict resource trends and breach timelines
dashboard	Launch the web UI

Common flags: --namespace/-n, --mode/-m {mock,k8s,prometheus}, --prometheus-url/-p, --strategy/-s {p95,p99,max}, --headroom 0.20, --top 10, --lookback 168.

Deployment

Docker

# Pull the published image (GitHub Container Registry)
docker run -p 8080:8080 ghcr.io/pallaprolus/kube-foresight:latest \
  dashboard --host 0.0.0.0 --port 8080 --demo

# …or build from source
docker build -t kube-foresight .
docker run -p 8080:8080 kube-foresight dashboard --host 0.0.0.0 --port 8080 --demo

Helm

helm install kube-foresight charts/kube-foresight \
  --set collector.mode=k8s \
  --set collector.namespaces=production \
  --set scheduler.enabled=true

See charts/kube-foresight/values.yaml for persistence, ingress, alerting, and authentication options.

Configuration

All settings are environment variables prefixed KF_:

Variable	Purpose	Default
KF_MODE	Collector mode (mock, k8s, prometheus)	k8s
KF_NAMESPACES	Comma-separated namespaces	default
KF_CLOUD_PROVIDER	Pricing source: aws, gcp, azure	aws
KF_SCHEDULER_ENABLED	Background collect/analyze loop	false
KF_COLLECT_INTERVAL	Collection interval (seconds)	300
KF_ANALYSIS_INTERVAL	Analysis interval (seconds)	900
KF_SLACK_WEBHOOK_URL	Slack alerts for at-risk deployments	—
KF_LOG_FORMAT	text or json	text

Development

git clone https://github.com/pallaprolus/kube-foresight && cd kube-foresight
pip install -e ".[k8s,dashboard,dev]"
pytest tests/ -v --tb=short        # 251 tests
ruff check .
helm lint charts/kube-foresight

For codebase layout, conventions, and the data-flow diagram, see docs/architecture.md.

Contributing

Issues and PRs are very welcome — particularly: real-world deployment reports, additional pricing providers, and validation of forecast accuracy on production traces. See CONTRIBUTING.md once filed.

License

Apache License 2.0