System overview
kube-res-foresight connects collection, forecasting, recommendations, and controlled actions for one Kubernetes cluster. Follow blue data relationships to see how advice is produced, then green control relationships to see where it is applied.
Prometheus scrapes workload and cluster metrics. The platform actively queries its HTTP API for history and recent samples. Metric arrows represent data relationships, not direct pushes from applications. Observed usage and Ready replicas return to collection and evaluation.
Dashed relationships are optional: time-series services produce numerical forecasts, while the AI assistant provides querying and analysis. Boxes represent responsibilities, not necessarily separate deployments.
Modules and responsibilities
| Module | Inputs and responsibilities | Outputs |
|---|---|---|
| Module and metric configuration | One workload per module, with metric sources, units, history, prediction mode, bounds, and authorization. | Collection and runtime policy for that workload. |
| Collection and quality | Render queries, read in segments, and check sampling, gaps, units, and freshness. | History on a consistent grid with quality information. |
| Forecasting and evaluation | Run selected methods, compare baselines in rolling backtests, and evaluate predictions when actuals arrive. | Forecasts, versions, eligibility, and performance records. |
| Decisions and safeguards | Combine lead time, consensus, capacity inputs, schedules, OOM/heap pressure, and bounds. | Resource specifications, target replicas, and reasons. |
| Advice and execution interfaces | Store versioned, expiring snapshots and expose resource advice and replica decisions separately. | Traceable advice and inputs for execution. |
| Task center | Schedule forecasting, backtests, evaluations, retention, and AI tasks, with failure and retry records. | Scheduled jobs and run history. |
| Administration and audit | Manage users, LDAP, permissions, connections, and settings; inspect actions, admissions, and degradation. | Managed configuration and operation history. |
The console manages these capabilities through Platform APIs. Platform and task entry points share business rules and a database and can be combined according to deployment needs. Logical modules do not require separate services.
Two independent execution paths
New Pod resources: API Server admission invokes Kyverno, whose policy queries validated, unexpired resource advice and applies authorized requests and managed limits. Admission does not wait for collection, inference, or long queries. Unavailable advice preserves original resources.
Workload replicas: the Operator reads modules and decisions from the platform, checks bounds, readiness, cooldown, and step limits, then writes replicas through the Kubernetes Scale API. It neither reads the platform database nor changes Pod requests/limits.
Authorize the paths separately. Only one controller may write a workload's replicas; the Operator and HPA/KEDA cannot control the same target simultaneously. Updated recommendations do not immediately resize running Pods.
Storage and external dependencies
| Component | Purpose and boundary |
|---|---|
| Prometheus | Supplies workload and cluster metrics. The platform queries it without replacing the metric store. |
| Relational database | Choose SQLite, MySQL, or PostgreSQL to retain settings, collected data, jobs, predictions, recommendations, and audits. |
| Time-series service, optional | Provides external forecasts and, where supported, background tuning. Failures follow candidate and fallback rules. |
| LLM and email, optional | The assistant queries records; scheduled tasks generate and email answers without directly writing resource or replica changes. |
| Kubernetes API | Handles admission and replica changes. Permissions, workload state, and readiness affect actual outcomes. |
Feedback and observability
Platform and Operator expose Prometheus metrics for monitoring, including with Grafana. Management views relate forecasts, advice, reported actions, admissions, and measured effectiveness. Execution does not wait for Prometheus to scrape decisions and read them back.