Metadata-Version: 2.4
Name: kube-foresight
Version: 0.3.0
Summary: Predictive Resource Optimizer for Kubernetes — identifies over-provisioned deployments and generates right-sizing patches
Author: Sudhakar Pallaprolu
License: Apache-2.0
Project-URL: Homepage, https://github.com/pallaprolus/kube-foresight
Project-URL: Repository, https://github.com/pallaprolus/kube-foresight
Project-URL: Issues, https://github.com/pallaprolus/kube-foresight/issues
Keywords: kubernetes,k8s,resource-optimization,right-sizing,cost-savings,prometheus,finops
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: k8s
Requires-Dist: kubernetes>=28.1.0; extra == "k8s"
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.104.0; extra == "dashboard"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "dashboard"
Requires-Dist: jinja2>=3.1.0; extra == "dashboard"
Requires-Dist: python-multipart>=0.0.6; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Dynamic: license-file

# kube-foresight

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

[![CI](https://github.com/pallaprolus/kube-foresight/actions/workflows/ci.yml/badge.svg)](https://github.com/pallaprolus/kube-foresight/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/kube-foresight.svg)](https://pypi.org/project/kube-foresight/)
[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://github.com/pallaprolus/kube-foresight/releases)

![Dashboard overview](docs/screenshots/overview.png)

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

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

Prefer a container? See [Deployment](#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.

```bash
# 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:

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

![Recommendations view](docs/screenshots/recommendations.png)

## 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/`](benchmarks/README.md).

## 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](https://github.com/robusta-dev/krr)** — Prometheus-based right-sizing recommendations.
- **[Goldilocks](https://github.com/FairwindsOps/goldilocks)** — surfaces VPA recommendations across a cluster.
- **[VPA](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler)** — in-cluster vertical autoscaling that can apply changes automatically.
- **[Kubecost / OpenCost](https://www.opencost.io/)** — 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

```bash
# 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

```bash
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`](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

```bash
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`](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`](CONTRIBUTING.md) once filed.

## License

Apache License 2.0
