Skip to content
GreenKube

Installation

One helm install, one sign-in, optionally one Secret for Git. There is no profile to choose and no feature flag to flip: GreenKube deploys the full loop and every capability activates itself when its prerequisites appear. Everything after Install is optional and additive.

You need a Kubernetes cluster you administer, Helm 3.10+ and kubectl. Prometheus and OpenCost are strongly recommended; GreenKube discovers both in the cluster.

  1. Install the chart

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

    Open the dashboard and sign in as admin with the initial password. You choose a new one at the first sign-in.

    Terminal window
    kubectl -n greenkube port-forward svc/greenkube-api 8000:8000 # then open http://localhost:8000
    kubectl -n greenkube get secret greenkube-initial-admin -o jsonpath='{.data.password}' | base64 -d; echo
  3. Connect Git (optional)

    GitOps discovery already runs. To let GreenKube open pull requests against the repositories your Argo CD or Flux sources point at, create one Secret. Delivery activates within a minute, with no upgrade and no restart:

    Terminal window
    kubectl -n greenkube create secret generic greenkube-git-credentials \
    --from-literal=token=<token with write access to the repositories> \
    --from-literal=host=github.com # the one Git host this token belongs to

    The token is only ever sent to the host named by host. Without that key it is used only when every discovered repository lives on github.com, or every one on gitlab.com; it is never sent to a self-hosted host the key does not name. Repositories on other hosts need an explicit provider.

  4. Check the Setup page

    The Setup page (/setup, or GET /api/v1/setup/status) shows what is active and, for anything missing, the exact fix.

Recommendations appear once enough evidence is collected, in two stages:

  • request increases and the other sources after config.recommendations.minSamples samples (36, about 3 hours with the default 5-minute step);
  • request decreases (usually most of the savings) only after config.recommendations.minDecreaseCoverageDays of history (7 days, so a weekly cycle is seen).

The Evidence warm-up check of the setup checklist shows both estimates. A pull request is never opened without the approval of a plan digest by a signed-in user.

Without OpenCost, GreenKube still prices every pod: it charges the pod’s reservation at its node’s list price (bundled catalogs for AWS, Azure, OVHcloud and Scaleway, cost_source: pricing_catalog) or at the rates you configure (impact.pricing.cpuCoreHour / ramGiBHour, cost_source: custom_rate). Those are estimates, not an observed allocation. OpenCost observes the allocation itself and is what change measurements trust first.

ComponentDefaultResponsibilities
greenkube-api Deployment1 replica, 100m / 128MiREST API, dashboard, webhooks, sign-in. No background job. Ready once the database schema is current.
greenkube-controller Deployment1 replica, 100m / 256MiEvery periodic loop: collection, scans, measurement, GitOps discovery and sync, automation readiness, plan execution. Migrates the database at startup. Leader election through the greenkube-leader Lease.
greenkube-renderer Deployment1 replica, 25m / 96MiIsolated Helm/Kustomize rendering: no Secret, no service-account token, egress-deny NetworkPolicy.
greenkube-postgres StatefulSet100m / 128Mi, 10 GiB volumeBundled PostgreSQL.
greenkube-worker Deployment0 replicasOptional extra plan executors (worker.replicas).

Requests total about 325m CPU and 600 MiB, small enough for kind or minikube. The chart also creates read-only cluster RBAC (nodes, pods, workloads, Services, volumes, Argo CD and Flux objects; never Secrets), a namespaced Role for the Lease, and a credentials bootstrap hook.

What activates when:

CapabilityActive whenOtherwise
Observe, recommend, measureAlways (each recommendation source activates when its probe succeeds)—
DiscoverArgo CD or Flux CRDs are present (re-checked every discovery interval)Dormant; the checklist explains how to connect a GitOps controller
PreviewA discovered, allowlisted repository with credentials and a resolved workload bindingThe recommendation shows the blocker and its fix
Deliver (open PRs)Preview + credentials + automation.policy.pauseDelivery: falseDormant with its reason
WebhooksA provider webhook Secret is configuredPolling only

Create a values file instead of --set flags, then helm upgrade greenkube greenkube/greenkube -n greenkube -f my-values.yaml:

my-values.yaml
config:
clusterName: prod-eu-west
cloudProvider: aws # aws, gcp, azure, ovh, scaleway, on-prem, unknown
defaultZone: FR # grid zone when node labels do not identify it
prometheus:
url: "" # empty: in-cluster discovery
secrets:
electricityMapsToken: "" # live grid carbon intensity (optional)

The chart ships a values.schema.json: invalid types and ranges are rejected before anything is applied. See Configuration for the values most often changed.

The Secret of step 3 is all most installations need. GreenKube infers the provider of each discovered repository host: github.com is GitHub, gitlab.com is GitLab, and a self-hosted host is identified by probing /api/v4/version (GitLab) or /api/v1/version (Gitea). Delete the Secret and delivery becomes dormant again; open pull requests stay tracked.

By default every repository referenced by a discovered Argo CD or Flux source is allowed (@discovered). Narrow it in values, or allow repositories one by one from the setup checklist:

automation:
repositoryAllowlist:
- acme/gitops
- acme/platform-*

Declare a provider explicitly only for several credentials, a self-hosted URL that cannot be probed, or a separate Secret; explicit entries win over inference:

automation:
providers:
- id: gitlab-internal
type: gitlab
apiBaseUrl: https://git.example.com/api/v4
secretName: gitlab-token
secretKey: token
repositoryAllowlist: ["platform/*"] # optional

GitHub Apps (with signed commits), GitLab project and group access tokens, delivery modes where your CI opens the pull request, and signed webhooks are covered in GitOps delivery.

postgres:
enabled: false
secrets:
dbConnectionString: postgresql://greenkube:<password>@db.example.com:5432/greenkube
config:
db:
sslMode: require

With secrets.existingSecret, put DB_CONNECTION_STRING in that Secret instead. The controller creates and migrates the schema (config.db.schema, default public) under a PostgreSQL advisory lock. SQLite is for greenkube demo and local development only; the chart no longer offers it.

Route one hostname to the API Service; the dashboard and the API share the origin, so no CORS is needed. The proxy must preserve the /api prefix and forward the Authorization, Cookie, Origin and X-CSRF-Token headers. Serve remote access over HTTPS: the session cookie travels with every request. When TLS terminates at the Ingress controller, set config.trustedProxyIps to its addresses so GreenKube marks the cookie Secure, or set auth.session.secureCookie: always. Set config.externalUrl for links in pull requests.

ingress:
enabled: true
className: nginx
hosts: [greenkube.example.com]
tls:
- secretName: greenkube-tls
hosts: [greenkube.example.com]
annotations:
cert-manager.io/cluster-issuer: letsencrypt
# or a Gateway API HTTPRoute attached to an existing Gateway
httpRoute:
enabled: true
parentRefs:
- name: shared-gateway
namespace: gateway-system
hostnames: [greenkube.example.com]

Browser users sign in with accounts and server-side sessions; machines use scoped API keys created in Settings > API keys (read, write, approve, plans:deliver, signals:write, signals:report, metrics:read, admin). To provide the first admin password yourself (GitOps), set auth.admin.existingSecret. Single sign-on works through an authentication proxy (config.apiAuthMode: proxy) or native OpenID Connect (config.apiAuthMode: oidc), with IdP groups mapped to the viewer, operator and admin roles.

A headless install in config.apiAuthMode: api_key has no accounts: its sign-in page asks for an API key (the bootstrap key GREENKUBE_API_KEY or a scoped gk_ key with the read scope) and answers with a signed cookie, never the key itself. It needs HTTPS, or kubectl port-forward to localhost; plain HTTP to a remote host is refused. Revoking the key, or rotating the bootstrap key, signs its browsers out. Use session mode for per-person accounts, roles and audit.

High availability is two numbers, not another install:

api:
replicas: 2
controller:
replicas: 2 # extra replicas are hot standbys: the Lease hands over within 30 s

API replicas are stateless and share sessions through PostgreSQL. Only the controller holding the greenkube-leader Lease runs the loops. With more than one replica the chart also renders a PodDisruptionBudget and a soft pod anti-affinity for the API and the controller.

Every pod the chart renders by default meets the Kubernetes Pod Security Standard restricted: non-root, no privilege escalation, all capabilities dropped and RuntimeDefault seccomp. One opt-in option is outside it: renderer.egressFirewall.enabled=true, meant only for CNIs that do not enforce NetworkPolicy.

TopicWhat to setReference
Cost allocationInstall OpenCost (required for verified cost savings on-premises and on providers without a bundled catalog)Why OpenCost
Backupspostgres.backup.enabled: true (daily pg_dump to its own volume), plus an off-cluster copyBackup and restore
UpgradesBack up first; helm upgrade --wait --timeout 15mUpgrading
Availabilityapi.replicas: 2, controller.replicas: 2High availability
Alertsmonitoring.prometheusRule.enabled: true with the ServiceMonitorAlerts and SLOs
CapacitySize the data volume for your pod count and retentionSizing
Credentialssecrets.existingSecret and auth.admin.existingSecret under GitOpsCredentials
ExposureIngress or HTTPRoute with TLSIngress and TLS
# production-values.yaml (example)
api:
replicas: 2
controller:
replicas: 2
postgres:
persistence:
size: 50Gi
storageClassName: gp3 # a class with allowVolumeExpansion: true
backup:
enabled: true
monitoring:
serviceMonitor:
enabled: true
prometheusRule:
enabled: true

The database grows with the number of pods running at the same time and with the retention of the hourly aggregates. Raw samples are kept config.metricsRawRetentionDays (7 days) and then compressed into hourly rows, kept config.metricsAggregatedRetentionDays (unbounded by default).

Per 100 concurrent pods (about 1.5 containers each)Size
Raw samples (7 days, steady state)about 0.3 GB
Hourly aggregates, per year of retentionabout 1.5 to 2 GB
Recommendations, plans, changes, measurements, ledgertens of MB per year
PostgreSQL overhead (WAL, dead rows)about 1.5 GB

The default 10 GiB volume holds roughly three years of history for 100 pods, or one year for 300 pods. Keep at least 30% free. The savings ledger, recommendations and measurements are never pruned by the retention settings.

The chart never generates a credential at render time (no lookup, no random function), so helm template output is stable under Argo CD and Flux. A bootstrap hook (an Argo CD PreSync hook) creates the Secret <release> only when it is absent, never rotates a value, and creates <release>-initial-admin once. It generates the scrape token GREENKUBE_METRICS_TOKEN, the ledger chain key LEDGER_CHAIN_KEY, GREENKUBE_API_KEY (api_key mode only) and the bundled PostgreSQL password. Back up the Secret with the database: entries chained with the ledger key only verify with it. For a fully declarative setup, set secrets.existingSecret and auth.admin.existingSecret; the chart then renders no Secret and runs no hook. Add a LEDGER_CHAIN_KEY key to that Secret (and GREENKUBE_METRICS_TOKEN with secrets.existingSecretHasMetricsToken: true).

Terminal window
helm uninstall greenkube --namespace greenkube

The PostgreSQL volume and the generated Secret greenkube survive uninstallation, so a reinstall reuses the data and its password. For a clean reinstall delete both:

Terminal window
kubectl -n greenkube delete pvc data-greenkube-postgres-0
kubectl -n greenkube delete secret greenkube greenkube-initial-admin
SymptomLikely causeAction
greenkube-api stays not ready, /api/v1/health returns migratingThe controller has not migrated the schema yet.kubectl -n greenkube logs deploy/greenkube-controller; a large upgrade can take minutes.
Controller crash-loops with password authentication failedA PostgreSQL volume from an earlier install was reused with another password.Delete data-greenkube-postgres-0, or put the original password in the Secret greenkube.
helm install fails with a values schema errorA value has the wrong type or is out of range.Fix the value named in the message.
helm upgrade fails with config.db.type=sqlite is no longer supportedA 0.3.x SQLite release.Follow Upgrading.
Setup checklist: delivery credentials_missingNo Git credentials are mounted.Create greenkube-git-credentials; it is read on the next readiness tick (within 60 s).
Setup checklist: credentials_host_ambiguous or credentials_host_mismatchThe token is not bound to a host, or the host key names a host no repository uses.Add or fix the host key; declare explicit providers for other hosts.
Setup checklist: renderer_egress_unenforcedThe network plugin does not enforce NetworkPolicy.Use a CNI that does, or renderer.egressFirewall.enabled=true. Previews still work.
Dashboard shows no dataPrometheus is unreachable or not discovered.Set config.prometheus.url.