Skip to content
GreenKube

The Optimization Loop

GreenKube is an optimization control loop for Kubernetes clusters managed with GitOps. It aggregates recommendations from several sources, decides which ones are worth doing, delivers them as pull requests, proves that the change reached the cluster and what it saved, and keeps a ledger of the outcome.

Sources ─► Signals ─► Recommendation ─► Plan (diff + digest) ─► Pull request
│ merge
Ledger ◄── Measurement ◄── Change (apply detection) ◄── Sync (Argo CD / Flux)
StageQuestion it answersRead more
AggregateWhat do my tools recommend, for which workloads?Sources
DecideWhich changes are worth it, and how risky are they?Recommendations
DeliverWhere does this workload live in Git, and what exactly changes?GitOps delivery
ProveDid the merge reach the cluster? Is the new configuration live? What did it save?Measurements and ledger
LedgerWhat have we saved so far, measured versus projected?Measurements and ledger
TermMeaning
SourceSomething that produces optimization advice: GreenKube’s native analyzers (rightsizing, orphaned LoadBalancers and PersistentVolumes), VPA, Goldilocks, Robusta KRR reports, or any tool using the push API. Each source is a plugin with its own health and run history.
SignalOne source’s proposal for one target and one capability (for example “container web of shop/api: CPU request 500m → 250m”), in one public schema. Signals are not recommendations.
RecommendationOne proposed change on one target, built by the consensus engine from the signals of every source: GreenKube’s measured value decides, the other sources move the confidence. It carries evidence, a projected impact, a risk level, a confidence score, an expected value and its delivery eligibility.
BindingWhere a workload is defined in Git (repository, ref, path, renderer), found by reading Argo CD Applications and Flux Kustomizations or HelmReleases.
PlanA validated set of file edits implementing one or more recommendations on one binding, identified by a digest. Approval binds to that digest.
Pull requestThe plan committed on a deterministic branch and opened on GitHub, GitLab or Gitea, with the evidence a reviewer needs.
SyncArgo CD or Flux reporting the merged revision as applied and healthy.
ChangeOne pod-template revision rolled out on one workload, recorded by apply detection with a frozen baseline snapshot of the 7 days before the merge.
MeasurementThe decision on a change after its post-window: counterfactual minus actual, with a 90% confidence interval, confounder checks and health gates. Outcome realized, not_realized, inconclusive or contaminated.
LedgerThe append-only, keyed hash-chained record of every amount saved, per hour, method and quantity, linked to the pull request, merge commit, synced revision and measurement.
Released capacityCPU cores and memory freed by a change, projected and measured, in their own units. Never converted to money.

Cost, energy and CO₂e per workload, namespace and node are collected all along: see Footprint and, for how energy and carbon are estimated, Energy & Carbon.

GreenKube distinguishes several kinds of savings figures and never adds them together:

KindMeaning
ProjectedThe expected annual impact of a recommendation, computed by the versioned Impact Model before the change.
Measured allocatedWhat the changed workload stops being charged, measured after the change against a counterfactual.
Expected billedThe measured allocated saving times the realization factor: the share expected to reach the bill once nodes are removed. Labelled as an expectation.
Realized (billed)Savings measured on the bill at node-pool level. On the roadmap: no such figure is produced yet, and the word “Realized” is reserved for it in the UI.
User declaredSavings declared on a manual apply. Never counted as measured.
ProcessResponsibilities
Controller (greenkube start)Every periodic loop: collection, carbon intensity, compression, recommendation scans, GitOps discovery, sync observation, apply detection, measurement, savings attribution, ledger verification, plan execution. Leader election in production.
API (greenkube-api)Stateless: REST API and dashboard, plan preview and approval, webhook ingress. Runs no background loop, so it scales horizontally.
Renderer sandboxRenders Kustomize and Helm snapshots with no access to the database, provider tokens or service-account token.
Automation worker (optional)Executes approved plan operations only, as extra capacity next to the controller.

See Architecture for the components and data flow.