Skip to content
GreenKube

Quick Start

Three steps, from zero to a merged and measured change:

  1. Look around in the demo (one docker run, no cluster).
  2. Install GreenKube on a disposable cluster with the accelerated quickstart values.
  3. Open your first pull request against a sample GitOps repository, merge it, and watch GreenKube follow it through the sync to a measurement.
Terminal window
docker run --rm -p 9000:9000 greenkube/greenkube demo --no-browser --port 9000
# Open http://localhost:9000, Ctrl+C to stop

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).

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.

SettingQuickstartDefault
config.prometheus.queryRangeStep30s5m
config.collection.maxBackfill30m24h
config.recommendations.minSamples636
config.recommendations.minDecreaseCoverageDays0.001 (about 90 seconds)7
config.recommendations.scanInterval1m1h
config.recommendations.verification.windowHours0.1 (6 minutes)72
automation.policy.minSamples / minCoverage6 / 036 / 0.5
automation.discoveryInterval / prPollIntervalSeconds / syncPollIntervalSeconds30s / 10 / 105m / 120 / 30

A disposable cluster (the scripted path targets Minikube with the Docker runtime) with:

ComponentUsed for
Prometheus (kube-prometheus) with cAdvisor and kube-state-metricsUsage and request samples
Metrics ServerPer-container usage
Argo CDGitOps delivery of the sample app
Flux (optional)A second delivery path
GiteaGit 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).

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:

Terminal window
export GITEA_TOKEN=<gitea token>
make quickstart

Under the hood, the install step is:

Terminal window
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:9090

The 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.

  1. Open the UI. kubectl -n greenkube port-forward svc/greenkube-api 8000 and open http://localhost:8000. Sign in as admin with 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.

  2. 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.

  3. 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.

  4. 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 3000 to follow the link).

  5. Merge it in Gitea. GreenKube sees the merge, waits for Argo CD to sync the merge commit (the plan becomes merged, then synced), and detects the new requests in the cluster (the recommendation becomes applied). This takes about a minute.

  6. 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.

On a real cluster, use the chart defaults: one install, one sign-in, optionally one Secret for Git.

Terminal window
helm repo add greenkube https://GreenKubeCloud.github.io/GreenKube && helm repo update
helm install greenkube greenkube/greenkube -n greenkube --create-namespace

Recommendations 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.

SymptomCheck
No recommendation after 10 minutesPrometheus URL and scraping of cAdvisor and kube-state-metrics; kubectl -n greenkube logs deploy/greenkube-controller -c controller
Recommendation not eligibleIts blockers (code, message, fix) on the detail page; warming_up gives the time it becomes eligible
Binding not resolvedThe provider apiBaseUrl host must match the Argo CD or Flux repository URL, and the repository must be in repositoryAllowlist
Plan stays mergedArgo CD or Flux has not synced the merge commit yet; check the Application or Kustomization
PR link unreachableRun kubectl -n gitea port-forward svc/gitea-http 3000, or set automation.providers[].webBaseUrl to your browser-facing Gitea origin