Configuration Reference

GreenKube follows the 12-Factor App methodology — all configuration is driven by environment variables. When deployed via Helm, these are set through values.yaml.

Helm Values Reference

Image

Parameter	Description	Default
image.repository	Docker image repository	greenkube/greenkube
config.logFormat	Log output format: json or console	json
config.metricsListMaxRangeDays	Maximum date range (days) for GET /api/v1/metrics	30
image.tag	Image tag	0.3.0
image.pullPolicy	Image pull policy	IfNotPresent

Database

Parameter	Description	Default
config.db.type	Storage backend: postgres, sqlite, elasticsearch	postgres
config.db.path	SQLite file path (if type is sqlite)	/data/greenkube_data.db
config.db.schema	PostgreSQL schema	public

Persistence (SQLite)

Parameter	Description	Default
config.persistence.enabled	Enable persistent storage for SQLite	false
config.persistence.storageClassName	Storage class name (empty = default)	""
config.persistence.accessMode	PVC access mode	ReadWriteOnce
config.persistence.size	PVC storage size	1Gi

Carbon & Energy

Parameter	Description	Default
config.cloudProvider	Cloud provider: aws, gcp, azure, ovh, scaleway, on-prem	unknown
config.defaultZone	Fallback carbon zone (ISO country code)	FR
config.defaultIntensity	Default grid intensity (gCO₂e/kWh) when API unavailable	500.0
config.electricityProvider	Grid intensity data provider: electricity_maps or wattnet (EU-only, free — see Wattnet guide)	electricity_maps
config.normalizationGranularity	Intensity lookup granularity: hour, day, none	hour
config.defaults.pue	Power Usage Effectiveness factor	1.3
config.defaults.instance.vcores	Default vCPU count for unknown instances	1
config.defaults.instance.minWatts	Default min watts per vCPU	1.0
config.defaults.instance.maxWatts	Default max watts per vCPU	10.0

Prometheus

Parameter	Description	Default
config.prometheus.url	Prometheus URL (empty = auto-discovery)	""
config.prometheus.verifyCerts	Verify TLS certificates	true
config.prometheus.queryRangeStep	Range query step interval	5m
config.prometheus.queryRangeMaxSamples	Max data points per range query	10000
config.prometheus.nodeInstanceLabel	Node label for instance type	label_node_kubernetes_io_instance_type

OpenCost

Parameter	Description	Default
config.opencost.url	OpenCost URL (empty = auto-discovery)	""
config.opencost.verifyCerts	Verify TLS certificates	true

Node Analysis

Parameter	Description	Default
config.nodeAnalysisInterval	Interval for node analysis	5m
config.nodeDataMaxAgeDays	Max age for historical node data	30

API Server

Parameter	Description	Default
config.api.enabled	Enable the API server	true
config.api.host	API listen address	0.0.0.0
config.api.port	API listen port	8000
config.corsOrigins	Allowed CORS origins (comma-separated)	*
config.apiRateLimit	Rate limit for API endpoints (slowapi format)	60/minute

Monitoring

Parameter	Description	Default
monitoring.serviceMonitor.enabled	Create a ServiceMonitor for Prometheus Operator	true
monitoring.serviceMonitor.namespace	Namespace for the ServiceMonitor (must match Prometheus selector)	monitoring
monitoring.serviceMonitor.interval	Scrape interval	30s
monitoring.networkPolicy.enabled	Create a NetworkPolicy allowing Prometheus to reach GreenKube	true
monitoring.networkPolicy.prometheusNamespace	Namespace where Prometheus runs	monitoring

Recommendations

Parameter	Description	Default
config.recommendations.lookbackDays	Days of data for analysis	7
config.recommendations.rightsizingCpuThreshold	CPU usage ratio triggering rightsizing	0.3
config.recommendations.rightsizingMemoryThreshold	Memory usage ratio triggering rightsizing	0.3
config.recommendations.rightsizingHeadroom	Safety headroom multiplier	1.2
config.recommendations.zombieCostThreshold	Cost threshold for zombie detection ($)	0.01
config.recommendations.zombieEnergyThreshold	Energy threshold for zombie detection (J)	1000
config.recommendations.autoscalingCvThreshold	CV threshold for autoscaling suggestion	0.7
config.recommendations.autoscalingSpikeRatio	Max/avg ratio for spike detection	3.0
config.recommendations.carbonAwareThreshold	Intensity ratio for carbon-aware scheduling	1.5
config.recommendations.nodeUtilizationThreshold	Node utilization threshold	0.2
config.recommendations.storageCostPerGibMonth	Fallback storage cost for orphaned PV savings when OpenCost has no data ($/GiB-month)	0.10
config.recommendations.loadBalancerCostPerMonth	Fallback cost for orphaned LoadBalancer savings when OpenCost has no data ($/month)	18.0
config.recommendSystemNamespaces	Include system namespaces in recommendations	false

Secrets

Parameter	Description	Default
secrets.electricityMapsToken	Electricity Maps API token	""
secrets.wattnetEmail	Wattnet account email (only when config.electricityProvider is wattnet)	""
secrets.wattnetPassword	Wattnet account password (only when config.electricityProvider is wattnet)	""
secrets.boaviztaToken	Boavizta API token	""
secrets.apiKey	Bearer token for API authentication (empty = no auth)	""
secrets.dbConnectionString	PostgreSQL connection string (only if not using bundled postgres)	""
secrets.prometheus.username	Prometheus basic auth username	""
secrets.prometheus.password	Prometheus basic auth password	""
secrets.prometheus.bearerToken	Prometheus bearer token	""

PostgreSQL (Bundled)

Parameter	Description	Default
postgres.enabled	Deploy bundled PostgreSQL	true
postgres.image.repository	PostgreSQL image	postgres
postgres.image.tag	PostgreSQL version	18-alpine
postgres.auth.username	Database username	greenkube
postgres.auth.password	Database password (auto-generated if empty)	""
postgres.auth.database	Database name	greenkube
postgres.persistence.enabled	Enable persistent storage	true
postgres.persistence.size	Storage size	1Gi

Resources

Parameter	Description	Default
resources.requests.cpu	CPU request	100m
resources.requests.memory	Memory request	128Mi
resources.limits.cpu	CPU limit	500m
resources.limits.memory	Memory limit	512Mi

Environment Variables

When running outside Helm (Docker, source), use these environment variables:

Variable	Description	Default
DB_TYPE	postgres, sqlite, elasticsearch	postgres
DB_CONNECTION_STRING	PostgreSQL connection URL	—
DB_PATH	SQLite file path	/data/greenkube_data.db
ELASTICSEARCH_HOSTS	Elasticsearch endpoint(s)	—
PROMETHEUS_URL	Prometheus server URL	Auto-discovery
OPENCOST_URL	OpenCost server URL	Auto-discovery
ELECTRICITY_MAPS_TOKEN	Electricity Maps API token	—
ELECTRICITY_PROVIDER	Grid intensity provider: electricity_maps or wattnet	electricity_maps
WATTNET_EMAIL	Wattnet account email (required when ELECTRICITY_PROVIDER=wattnet)	—
WATTNET_PASSWORD	Wattnet account password (required when ELECTRICITY_PROVIDER=wattnet)	—
BOAVIZTA_TOKEN	Boavizta API token	—
CLOUD_PROVIDER	aws, gcp, azure, ovh, scaleway, on-prem	unknown
DEFAULT_ZONE	Fallback carbon zone	FR
DEFAULT_INTENSITY	Fallback grid intensity (gCO₂e/kWh)	500.0
DEFAULT_EMBODIED_EMISSIONS_KG	Fallback embodied emissions when Boavizta has no data	100.0
DEFAULT_HARDWARE_LIFESPAN_YEARS	Cloud hardware lifespan assumption	4
LOG_LEVEL	Logging level	INFO
NORMALIZATION_GRANULARITY	hour, day, none	hour
PROMETHEUS_QUERY_RANGE_STEP	Range query step	5m
API_HOST	API listen address	0.0.0.0
API_PORT	API listen port	8000
LOG_FORMAT	Log output format: json (structured, Loki-ready) or console (human-readable)	json
METRICS_LIST_MAX_RANGE_DAYS	Maximum date range (days) allowed for GET /api/v1/metrics raw listing; requests wider than this return HTTP 400	30
GREENKUBE_API_KEY	Bearer token for API authentication (empty = no auth)	—
CORS_ORIGINS	Allowed CORS origins (comma-separated)	*
RIGHTSIZING_CPU_THRESHOLD	CPU rightsizing threshold	0.5
ZOMBIE_COST_THRESHOLD	Zombie detection cost ($)	0.01
METRICS_RAW_RETENTION_DAYS	Days to keep 5-min raw metrics	7
METRICS_AGGREGATED_RETENTION_DAYS	Days to keep hourly aggregates (-1 = infinite)	-1
METRICS_COMPRESSION_AGE_HOURS	Age after which raw metrics are compressed	24
DB_POOL_MIN_SIZE	PostgreSQL min connection pool size	1
DB_POOL_MAX_SIZE	PostgreSQL max connection pool size	10
DB_STATEMENT_TIMEOUT_MS	PostgreSQL per-statement timeout (ms)	30000
TRUST_AUTH_PROXY	Read the authenticated user from X-Forwarded-User/X-Auth-Request-User headers instead of GreenKube’s own auth (for use behind Authentik, Caddy forward_auth, etc.)	false
STORAGE_COST_PER_GIB_MONTH	Fallback cost for orphaned PV recommendations ($/GiB-month)	0.10
LOAD_BALANCER_COST_PER_MONTH	Fallback cost for orphaned LoadBalancer recommendations ($/month)	18.0

Tip

GreenKube works without an Electricity Maps token. When no token is provided, the DEFAULT_INTENSITY value (default: 500 gCO₂e/kWh) is used for all zones. For accurate, zone-specific carbon data, get a free token at electricitymaps.com.