Quick Start
Three steps, from zero to a merged and measured change:
- Look around in the demo (one
docker run, no cluster). - Install GreenKube on a disposable cluster with the accelerated quickstart values.
- Open your first pull request against a sample GitOps repository, merge it, and watch GreenKube follow it through the sync to a measurement.
1. Try the demo
Section titled “1. Try the demo”docker run --rm -p 9000:9000 greenkube/greenkube demo --no-browser --port 9000# Open http://localhost:9000, Ctrl+C to stopOpen demo.greenkube.cloud: the full dashboard with realistic sample data, nothing to install.
The demo runs on a temporary SQLite database with a two-year sample history: recommendations, costs, emissions and node history. Use it to see the Overview, the ranked recommendations with their evidence, the changes board and the ledger before you install anything. greenkube demo --days N changes the number of recent days generated at hourly resolution (30 by default).
2. Install with the quickstart values
Section titled “2. Install with the quickstart values”The quickstart values (docs/examples/quickstart/values.yaml) accelerate evidence so that a rightsizing pull request can be opened minutes after install instead of days.
| Setting | Quickstart | Default |
|---|---|---|
config.prometheus.queryRangeStep | 30s | 5m |
config.collection.maxBackfill | 30m | 24h |
config.recommendations.minSamples | 6 | 36 |
config.recommendations.minDecreaseCoverageDays | 0.001 (about 90 seconds) | 7 |
config.recommendations.scanInterval | 1m | 1h |
config.recommendations.verification.windowHours | 0.1 (6 minutes) | 72 |
automation.policy.minSamples / minCoverage | 6 / 0 | 36 / 0.5 |
automation.discoveryInterval / prPollIntervalSeconds / syncPollIntervalSeconds | 30s / 10 / 10 | 5m / 120 / 30 |
Prerequisites
Section titled “Prerequisites”A disposable cluster (the scripted path targets Minikube with the Docker runtime) with:
| Component | Used for |
|---|---|
| Prometheus (kube-prometheus) with cAdvisor and kube-state-metrics | Usage and request samples |
| Metrics Server | Per-container usage |
| Argo CD | GitOps delivery of the sample app |
| Flux (optional) | A second delivery path |
| Gitea | Git server for the sample repository |
| OpenCost (optional) | Observed costs |
On your workstation: kubectl, helm, curl, jq, minikube, a clone of the GreenKube repository, and a Gitea API token with read/write repository scope whose user owns the sample repository (GITEA_OWNER, default greenkube).
Install
Section titled “Install”The scripted path builds the GreenKube image from your checkout inside Minikube (no registry needed), creates the sample repository and the Argo CD/Flux objects, and installs the chart with the quickstart values. It only runs against the minikube context (E2E_KUBE_CONTEXT to change it) and only touches objects labelled greenkube.io/e2e=true:
export GITEA_TOKEN=<gitea token>make quickstartUnder the hood, the install step is:
kubectl -n greenkube create secret generic greenkube-git --from-literal=token="$GITEA_TOKEN"helm upgrade --install greenkube ./helm-chart -n greenkube --create-namespace \ -f docs/examples/quickstart/values.yaml \ --set config.prometheus.url=http://prometheus-k8s.monitoring.svc.cluster.local:9090The values declare one Gitea provider whose allowlist is the sample repository only. The sample app has two deliberately oversized workloads: oversized-web (raw YAML, deployed by Argo CD; requests 400m CPU and 384Mi) and oversized-worker (a Kustomize overlay deployed by Flux; 300m and 256Mi). Both use almost nothing.
3. Your first pull request
Section titled “3. Your first pull request”-
Open the UI.
kubectl -n greenkube port-forward svc/greenkube-api 8000and openhttp://localhost:8000. Sign in asadminwith the initial password (kubectl -n greenkube get secret greenkube-initial-admin -o jsonpath='{.data.password}' | base64 -d); you choose a new one at the first sign-in. The Setup page shows which capabilities are active (discovery, delivery, sync tracking, measurement) and the fix for anything missing. -
Wait for evidence. Within 3 to 5 minutes, CPU and memory rightsizing recommendations appear for
greenkube-e2e-apps/oversized-web. Each one shows its evidence, projected impact (cost, CO₂e and released capacity), risk, confidence and delivery eligibility. A blocked recommendation lists each blocker with its fix. -
Preview the plan. Click Open PR. GreenKube resolves the workload’s binding to the sample repository, renders the change and shows the exact diff with its
sha256:digest. -
Approve. Approving binds to that digest: the reviewed change is exactly the committed change. The pull request opens in Gitea about 5 seconds later (
kubectl -n gitea port-forward svc/gitea-http 3000to follow the link). -
Merge it in Gitea. GreenKube sees the merge, waits for Argo CD to sync the merge commit (the plan becomes
merged, thensynced), and detects the new requests in the cluster (the recommendation becomesapplied). This takes about a minute. -
See the verdict. About 10 minutes after the merge the quickstart verifier decides. Follow the change on the Changes board (Plan → PR → Merged → Synced → Applied → Measuring → Outcome) and in the Ledger.
To run the whole loop unattended, use make e2e. It is destructive by default (E2E_FRESH=1): it first removes what a previous run created, including the GreenKube release, its PostgreSQL volume and the sample repository (only objects carrying the ownership marker). make e2e-status prints the result of every step and make e2e-clean removes everything the harness created.
Measuring against a counterfactual in the demo
Section titled “Measuring against a counterfactual in the demo”The quickstart decides merged changes with the short verifier, so change measurement is off and /changes stays empty. To record merged changes and measure them against a counterfactual on accelerated windows (a 6-hour baseline and a 72-minute post-window, decided about 80 minutes after the merge), add -f docs/examples/quickstart/values-change-measurement.yaml.
Install for real
Section titled “Install for real”On a real cluster, use the chart defaults: one install, one sign-in, optionally one Secret for Git.
helm repo add greenkube https://GreenKubeCloud.github.io/GreenKube && helm repo updatehelm install greenkube greenkube/greenkube -n greenkube --create-namespaceRecommendations then need real evidence: request increases and the other sources appear after about 3 hours (36 samples at the default 5-minute step), request decreases only after 7 days of history so that a weekly cycle is seen.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| No recommendation after 10 minutes | Prometheus URL and scraping of cAdvisor and kube-state-metrics; kubectl -n greenkube logs deploy/greenkube-controller -c controller |
| Recommendation not eligible | Its blockers (code, message, fix) on the detail page; warming_up gives the time it becomes eligible |
| Binding not resolved | The provider apiBaseUrl host must match the Argo CD or Flux repository URL, and the repository must be in repositoryAllowlist |
Plan stays merged | Argo CD or Flux has not synced the merge commit yet; check the Application or Kustomization |
| PR link unreachable | Run kubectl -n gitea port-forward svc/gitea-http 3000, or set automation.providers[].webBaseUrl to your browser-facing Gitea origin |