This document describes the current technical architecture of GreenKube, a lightweight platform for estimating, reporting, and optimizing the carbon footprint and cost of Kubernetes workloads.
flowchart TB
subgraph K8s["Kubernetes Cluster"]
Prom["Prometheus"]
OC["OpenCost"]
K8sAPI["K8s API"]
EM["Electricity Maps API"]
WN["Wattnet API"]
Boavizta["Boavizta API"]
GITOPS["Argo CD / Flux"]
end
subgraph External["Git providers"]
GIT["GitHub / GitLab / Gitea"]
end
subgraph GreenKube["GreenKube"]
direction TB
subgraph Collectors["Collectors (Input Adapters)"]
PC["PrometheusCollector"]
OCC["OpenCostCollector"]
NC["NodeCollector"]
PodC["PodCollector"]
EMC["ElectricityMapsCollector"]
WNC["WattnetCollector"]
BC["BoaviztaCollector"]
end
subgraph Core["Core (Business Logic)"]
DP["DataProcessor<br/>(Facade)"]
CO["CollectionOrchestrator<br/>(Parallel Fetch)"]
Est["BasicEstimator<br/>(CPU → Joules)"]
Calc["CarbonCalculator<br/>(Joules → CO₂e)"]
MA["MetricAssembler<br/>(Build CombinedMetric)"]
NZM["NodeZoneMapper<br/>(Cloud → eMaps Zone)"]
PRM["PrometheusResourceMapper<br/>(Per-Pod Resources)"]
CN["CostNormalizer<br/>(Per-Step Cost)"]
ESvc["EmbodiedEmissionsService<br/>(Boavizta Cache + Fallback)"]
SR["SummaryRefresher<br/>(Pre-computed Cache)"]
HRP["HistoricalRangeProcessor<br/>(Chunked Range)"]
Rec["OptimizationEngine<br/>(multi-source + evidence)"]
end
subgraph Storage["Storage (Output Adapters)"]
PG["PostgreSQL"]
SQLite["SQLite"]
end
subgraph Automation["GitOps automation"]
Disc["Discovery<br/>Argo CD / Flux"]
Bind["Workload<br/>bindings"]
PlanSvc["Plan service<br/>snapshot + render + diff"]
Renderer["Isolated<br/>renderer"]
Worker["Plan worker<br/>PR + polling"]
Sync["Controller sync<br/>+ apply detection"]
end
subgraph Presentation["Presentation"]
API["FastAPI<br/>REST API"]
CLI["Typer CLI"]
Dash["SvelteKit<br/>Dashboard"]
Grafana["Grafana<br/>(via Prometheus)"]
end
end
Prom --> PC
OC --> OCC
K8sAPI --> NC
K8sAPI --> PodC
EM --> EMC
WN --> WNC
Boavizta --> BC
PC --> CO
OCC --> CO
PodC --> CO
NC --> DP
CO --> DP
EMC --> DP
WNC --> DP
BC --> ESvc
DP --> Est
DP --> NZM
DP --> PRM
DP --> CN
DP --> MA
DP --> HRP
DP --> SR
MA --> Calc
MA --> ESvc
MA --> Storage
SR --> Storage
Storage --> API
Storage --> CLI
API --> Dash
API --> Grafana
Storage --> Rec
Rec --> API
K8sAPI --> Disc
GITOPS --> Disc
Disc --> Bind
Bind --> PlanSvc
PlanSvc --> Renderer
PlanSvc --> Storage
Worker --> GIT
GIT --> Sync
GITOPS --> Sync
Sync --> Storage
Storage --> Worker
Rec --> PlanSvc
GreenKube runs scheduled collection and recommendation lifecycles alongside an API and dashboard for querying stored data. An optional GitOps automation path discovers workload sources, renders and validates plans, executes approved pull requests, and observes controller sync and apply state. The CLI starts the collector or a local demo; it does not provide ad-hoc report or recommendation commands.
The system is designed around the principles of Clean Architecture and Hexagonal Architecture:
All I/O operations use Python’s asyncio for high-performance, non-blocking concurrent execution.
The core business logic (src/greenkube/core) NEVER depends on a specific storage implementation. This is enforced through:
CarbonIntensityRepository, NodeRepository)src/greenkube/core/factory.py instantiates the appropriate repository based on configurationSupported backends:
Cloud-specific details (AWS, GCP, Azure, OVH, Scaleway) are isolated in:
src/greenkube/utils/region_mapping.py (cloud region → carbon zone)src/greenkube/energy/instance_profiles.py (instance type → power characteristics)asyncio.gather for parallel data collectionAll collectors are fully asynchronous and implement a common pattern.
asyncio.gather)httpx.AsyncClient for non-blocking HTTP requestsPrometheusMetric (aggregated result with all metric lists)kubernetes_asyncio client for async K8s API callsDict[str, NodeInfo] (node name → metadata)List[PodMetric]List[CostMetric]/v1/footprints), token-based auth (/token-request/get_token)footprint_type=water) is not consumed yet — see docs/wattnet.mdcollect(zone, target_datetime))Selection: ELECTRICITY_PROVIDER config (electricity_maps |
wattnet), instantiated by the factory |
EmbodiedRepositoryEmbodiedEmissionsService injects a profile using DEFAULT_EMBODIED_EMISSIONS_KG (default: 100 kg CO₂e) and marks the metric as estimatedPrometheusMetric (CPU usage rates per pod)DEFAULT_INSTANCE_PROFILE when node type unknownList[EnergyMetric] (Joules per pod)The main orchestrator that coordinates the data pipeline from collection to metric assembly.
Architecture: The processor acts as a facade, delegating specialized work to focused collaborators while managing the overall pipeline flow.
Key Responsibilities:
Pipeline Stages:
run()): Real-time collection using Prometheus instant queries, structured into four explicit phases:
run_range()): Historical analysis with day-sized chunking for memory efficiencyImplementation Pattern:
CO2e = (kWh * grid_intensity * PUE) / 1000(zone, timestamp) → intensityCarbonResult (CO2e grams, grid intensity, timestamp)24h, 7d, 30d, 1y, ytd)metrics_summary (scalar totals per window) and metrics_timeseries_cache (ordered time buckets per window)POST /api/v1/metrics/dashboard-summary/refreshAnalyzes CombinedMetric data to identify optimization opportunities. It is the single orchestration path used by API recommendation requests and the startup scan (src/greenkube/core/optimization/). The CLI does not expose a recommendation command.
Pipeline: build an OptimizationContext (metrics window + node/HPA/PV/LB inputs) → run enabled sources → normalize/arbitrate/deduplicate → attach an evidence block and a risk/confidence/effort assessment → compute the multi-criteria ranking score → persist and reconcile.
Sources:
greenkube) — the built-in analyzers:
VPA (vpa, optional) — reads recommendation-mode VerticalPodAutoscalers (updateMode: Off) and replaces native CPU/memory rightsizing for the same workload, avoiding duplicate advice.
karpenter, optional) — node-pool consolidation recommendations when compatible Karpenter CRDs are available.Evidence, risk and ranking: every recommendation carries observation window, utilization distribution, current vs proposed resources, expected savings and method, confidence, reliability risk, rollback conditions, a machine-readable patch plan and an expiry date. Ranking profiles (balanced, carbon_first, cost_first, quick_wins, low_risk) combine impact, confidence, risk, effort, actionability and source authority.
For the user-facing automation workflow and supported source layouts, see GitOps automation.
Configuration: All thresholds, source flags and ranking settings are configurable via config.py and Helm values.
Repositories use asynchronous drivers for high-performance database interactions. All implement abstract base classes to ensure database agnosticism.
Abstract base class for carbon intensity storage.
Implementations:
asyncpg (native async PostgreSQL)carbon_intensity table with zone, timestamp, intensityaiosqlite (async SQLite wrapper)Abstract base class for node state snapshots.
Implementations:
node_snapshots table with timestamp, name, instance_type, zone, capacityStores final aggregated metrics (energy + carbon + cost + resources).
Schema (33 columns):
co2e_grams — indirect emissions from purchased electricity (grid intensity × energy × PUE)embodied_co2e_grams — upstream hardware manufacturing emissions (Boavizta, allocated by CPU share)total_co2e_grams — computed field, full pod carbon footprintMigrations: All backends support automatic schema evolution (ADD COLUMN IF NOT EXISTS)
Caches Boavizta API responses for hardware embodied emissions.
Schema: provider, instance_type, gwp_manufacture, lifespan_hours, last_updated
Stores pre-computed KPI scalar totals per window.
Schema: window_slug, namespace, total_co2e_grams, total_embodied_co2e_grams, total_cost, total_energy_joules, pod_count, namespace_count, updated_at
Stores pre-computed time-series buckets per window and granularity.
Schema: window_slug, namespace, bucket_ts, co2e_grams, embodied_co2e_grams, total_cost, joules
src/greenkube/api//api/v1/docsEndpoints:
GET /api/v1/health — Health check and versionGET /api/v1/health/services — Health status for all data sources (Prometheus, OpenCost, Electricity Maps, Wattnet, Boavizta, Kubernetes)GET /api/v1/health/services/{name} — Health status for a single data sourcePOST /api/v1/config/services — Update service URLs or tokens at runtimeGET /api/v1/config — Current configuration (sanitized secrets)GET /api/v1/metrics — Per-pod metrics with filteringGET /api/v1/metrics/summary — Aggregated totals (on-demand, full scan)GET /api/v1/metrics/timeseries — Time-series data with granularity (on-demand, full scan)GET /api/v1/metrics/dashboard-summary — Pre-computed KPI scalars from cache (fast, no full scan)GET /api/v1/metrics/dashboard-timeseries/{window_slug} — Pre-computed time-series buckets from cache (24h, 7d, 30d, 1y, ytd)POST /api/v1/metrics/dashboard-summary/refresh — Trigger on-demand background refresh of all cache tables (HTTP 202)GET /api/v1/namespaces — Active namespaces listGET /api/v1/nodes — Node inventoryGET /api/v1/recommendations — Optimization suggestionsGET /api/v1/recommendations/{id} — Full evidence, risk, ranking, and lifecycle detailGET /api/v1/recommendations/{id}/events — Recommendation audit trailPOST /api/v1/recommendations/{id}/apply-pr — Compatibility route through the validated GitOps plan pathGET /api/v1/gitops/status — Controller capability and discovery freshnessGET /api/v1/gitops/bindings — Workload binding pages and manual-resolution candidatesPOST /api/v1/gitops/refresh — Explicit discovery refreshGET /api/v1/automation/status — Worker heartbeat, queue, discovery, renderer, and provider readinessPOST /api/v1/automation/plans — Create a digest-addressed plan previewPOST /api/v1/automation/plans/{id}/approve — Approve the exact preview digestPOST /api/v1/automation/plans/{id}/rollback-preview — Create an inverse preview for a synced planPOST /api/v1/webhooks/{provider_id} — Signed provider webhook ingressGET /api/v1/report/summary — Report preview (row count, totals, unique pods/namespaces)GET /api/v1/report/export — Stream a report file (CSV or JSON) for direct browser downloadReport export query parameters:
format — csv (default) or jsonlast — time range string (1h, 24h, 7d, 30d, 1y, etc.)namespace — filter to a single namespaceaggregate — true to aggregate by (namespace, pod, period)granularity — grouping when aggregate=true: hourly, daily, weekly, monthly, yearlyfrontend/ssr = false, prerender = false in frontend/src/routes/+layout.js)/Pages:
/ — Dashboard (KPIs, charts, breakdown)/nodes — Node inventory/recommendations — Optimization recommendations, evidence, plan preview, pull requests/automation — GitOps discovery, workload binding coverage, manual resolution, automation readiness/report — Report builder: choose time range, namespace, aggregation, format and download CSV/JSON/settings — Configuration, service health overview with color-coded status indicators, and runtime service configurationFeatures:
src/greenkube/cli/greenkube start — Run the collector and scheduler as a background servicegreenkube demo — Launch demo mode with sample datagreenkube version — Show version infoThe REST API is started by the separate greenkube-api entry point (greenkube.api.app:main).
dashboards/greenkube-grafana.json/prometheus/metricsServiceMonitor, NetworkPolicy, Prometheus RBACUsed for real-time monitoring and scheduled collection.
NodeCollector.collect()
└─ Node metadata (instance type, zone, capacity, provider)
└─ Build node_instance_map directly from Phase-1 data
NodeZoneMapper.map_nodes(nodes_info)
└─ Map cloud region → Electricity Maps zone per node
asyncio.gather(
┌─ CollectionOrchestrator.collect_all(nodes_info):
│ ├─ PrometheusCollector.collect()
│ │ ├─ CPU usage (8 concurrent queries)
│ │ ├─ Memory usage
│ │ ├─ Network I/O (rx + tx)
│ │ ├─ Disk I/O (read + write)
│ │ ├─ Restart counts
│ │ └─ Node labels (enriched with Phase-1 data)
│ ├─ OpenCostCollector.collect()
│ │ └─ Cost allocation data
│ └─ PodCollector.collect()
│ └─ Resource requests (CPU, memory, storage)
└─ EmbodiedEmissionsService.prepare_embodied_data(nodes_info):
├─ Check EmbodiedRepository cache
├─ Fetch missing profiles from Boavizta API
└─ Inject fallback profile (DEFAULT_EMBODIED_EMISSIONS_KG) for unknowns
)
├─ BasicEstimator.estimate() → EnergyMetric per pod (Joules)
├─ MetricAssembler.prefetch_intensities()
│ ├─ Group pods by zone
│ └─ Prefetch intensity for (zone, timestamp) pairs
└─ MetricAssembler.assemble()
├─ CarbonCalculator.calculate_emissions()
├─ EmbodiedEmissionsService.calculate_pod_embodied()
│ └─ Mark metric is_estimated=True if fallback used
└─ Build CombinedMetric (energy + carbon + cost + resources + metadata)
Repository.write_combined_metrics()
└─ Batch insert to database (Postgres/SQLite)
SummaryRefresher.run()
├─ For each window (24h, 7d, 30d, 1y, ytd):
│ ├─ aggregate_summary() → MetricsSummaryRow → upsert metrics_summary
│ └─ aggregate_timeseries() → TimeseriesCachePoint[] → upsert metrics_timeseries_cache
└─ Repeated for each namespace
Used for reporting over time ranges with historical accuracy.
NodeRepository.get_latest_snapshots_before(start)
NodeRepository.get_snapshots(start, end)
└─ Reconstruct node timeline
For each chunk (1 day):
├─ Prometheus range queries (concurrent):
│ ├─ CPU usage over time
│ ├─ Network I/O over time
│ ├─ Disk I/O over time
│ ├─ Restart counts over time
│ └─ (5 queries via asyncio.gather)
│
├─ Parse time-series data:
│ └─ Build per-pod resource maps from range results
│
├─ Energy estimation per timestamp:
│ └─ Use historical node profile at each timestamp
│
├─ Carbon calculation:
│ └─ Historical intensity lookup
│
└─ Generate CombinedMetrics for chunk
Collect all chunks → Filter by namespace → Return
Build OptimizationContext from repository (last N days) + node/HPA/PV/LB inputs
OptimizationEngine.generate()
├─ Run enabled sources (native analyzers, VPA)
├─ Normalize provenance and arbitrate conflicts by capability/priority
├─ Deduplicate and clamp values to configured minimums
├─ Attach evidence, risk/confidence/effort and expiry
└─ Compute multi-criteria ranking score and factors
Return List[Recommendation] with:
├─ Type, source and provenance
├─ Affected resources (current vs recommended)
├─ Evidence (window, percentiles, rollback conditions, patch plan)
├─ Expected savings (cost + CO2e) and confidence
└─ Risk level, effort and ranking score
Upsert active records by target identity; mark absent actives as stale
Argo CD Application status + Flux inventories + live workloads
└─ Persist generation-bound workload bindings
Recommendation IDs (never repository/path/credentials)
└─ Resolve binding → snapshot immutable revision → render → validate → expiring digest
Exact digest approval
└─ Durable operation queue → worker revalidation
└─ Atomic multi-file commit → deterministic branch → pull request
Webhook/polling update → controller observes exact source revision
└─ actions sync_pending; plan merged → synced (or sync_failed after timeout)
└─ Apply detection compares per-container requests
└─ Normal post-apply health and savings verification
Only CPU and memory rightsizing recommendations have action planners. Unsupported sources and renderers fail closed with typed reasons. See GitOps automation for the supported matrix and security model.
All configuration flows through src/greenkube/core/config.py:
Database:
DB_TYPE — postgres |
sqlite |
DB_CONNECTION_STRING — PostgreSQL connection URLDB_PATH — SQLite file pathExternal Services:
PROMETHEUS_URL — Override auto-discoveryOPENCOST_API_URL — Override auto-discoveryELECTRICITY_MAPS_TOKEN — API token (optional)WATTNET_EMAIL / WATTNET_PASSWORD — Wattnet provider credentials (optional)BOAVIZTA_TOKEN — API token (optional)Collection:
PROMETHEUS_QUERY_RANGE_STEP — Default: 5mNODE_ANALYSIS_INTERVAL — Default: 5mNODE_DATA_MAX_AGE_DAYS — Default: 30Carbon:
DEFAULT_ZONE — Fallback carbon zoneDEFAULT_INTENSITY — Fallback intensity (gCO2e/kWh)NORMALIZATION_GRANULARITY — hour |
day | none |
DEFAULT_EMBODIED_EMISSIONS_KG — Fallback embodied emissions when Boavizta API returns no data (default: 100 kg CO₂e)Recommendations:
RECOMMENDATION_LOOKBACK_DAYS — Default: 7RIGHTSIZING_CPU_THRESHOLD — Default: 0.3ZOMBIE_COST_THRESHOLD — Default: 0.01RECOMMENDATION_MAX_METRIC_ROWS — Default: 750000RECOMMENDATION_TTL_DAYS — Default: 14VERIFICATION_* — post-apply verification gatesAutomation:
AUTOMATION_ENABLED — Default: falseAUTOMATION_MODE — disabled, inline, or workerGITOPS_DISCOVERY_INTERVAL / GITOPS_BINDING_TTLGITOPS_PROVIDERS_JSON — Secret-reference provider registryGITOPS_RENDERER_URL — isolated renderer serviceGITOPS_POLICY_JSON / GITOPS_PULL_REQUESTS_JSONGITOPS_WEBHOOK_SECRET_FILE, GITOPS_HELM_KUBE_VERSION, GITOPS_HELM_API_VERSIONS_JSONhelm-chart/
├── Chart.yaml # Chart metadata
├── values.yaml # Standalone/default configuration
├── values-production.yaml # Production profile overlay
└── templates/
├── deployment.yaml # Standalone collector + API
├── production-deployments.yaml # API, controller, automation worker
├── api-service.yaml # API/UI ClusterIP Service
├── automation-worker.yaml # Standalone worker mode
├── configmap.yaml # Non-secret config
├── secret.yaml # Tokens and credentials
├── migration-job.yaml # Production schema migration hook
├── leader-lease.yaml # Production controller Lease
├── renderer-sandbox.yaml # Isolated Helm/Kustomize renderer
├── postgres-*.yaml # PostgreSQL StatefulSet (optional)
├── serviceaccount.yaml # K8s RBAC
└── clusterrole.yaml # Read permissions for nodes/pods/GitOps
Dockerfile (multi-stage):
1. Frontend Builder (Node 22):
├─ npm ci (install deps)
├─ npm run build (SvelteKit static build)
└─ Output: static files in build/
2. Python Builder:
├─ uv sync / build the wheel from pyproject.toml
└─ Install into an isolated prefix
3. Final Image (Python 3.14-slim):
├─ Copy Python packages from builder
├─ Copy frontend build from frontend-builder
├─ Run as non-root user 'greenkube'
└─ ENTRYPOINT: greenkube CLI
Controlled by NORMALIZATION_GRANULARITY:
2024-02-21T14:37:22Z → 2024-02-21T14:00:00Z2024-02-21T14:37:22Z → 2024-02-21T00:00:00ZCarbonCalculator Cache:
(zone, normalized_timestamp_iso)Repository Cache:
Boavizta Cache:
EmbodiedRepository)is_fallback=True is injected using DEFAULT_EMBODIED_EMISSIONS_KG; the resulting metric is flagged is_estimated=TrueDashboard Summary Cache:
metrics_summary + metrics_timeseries_cache)SummaryRefresherasyncio.gatherrun_range() processes 1 day at a timedel statements for large intermediate structuressrc/greenkube/corestorage/base_repository.py)utils/ or energy/ mapping fileslogging.getLogger(__name__)async def for I/O operationsasyncio.gather for concurrent operationsruff format before commits (pre-commit hook)ruff check --fix to auto-fix issuesFollow conventional commits:
feat: — New featurefix: — Bug fixdocs: — Documentation onlytest: — Test additions/changesrefactor: — Code restructuringperf: — Performance improvementsThe recommendation-to-GitOps composition is intentionally fail-soft at external boundaries:
| Boundary | Recovery contract | Verification |
|---|---|---|
| Startup recommendation refresh | Runs in a tracked background task; provider or database errors are logged and do not prevent liveness traffic. | tests/integration/test_gitops_closed_loop.py::test_startup_refresh_failure_does_not_block_shutdown_or_health_state |
| Savings ledger write | A transient ledger failure is logged and returns zero; the collection loop continues and can retry on its next period. | tests/integration/test_gitops_closed_loop.py::test_savings_ledger_failure_is_recoverable |
| Rollback transition | Recommendations in rollback_review or reverted stop producing new ledger attribution while their history remains queryable. |
tests/integration/test_gitops_closed_loop.py::test_rollback_review_stops_future_savings_attribution |
The API liveness endpoint does not probe optional providers. Readiness is marked only after the database connection succeeds and is cleared before shutdown. This keeps restarts and provider outages observable without turning a transient dependency failure into a process-wide failure.
Multi-Cluster Support:
Advanced Analytics:
Real-Time Streaming:
Extended Metrics:
Enhanced Reporting:
New Collectors:
core/factory.pyDataProcessor to use itNew Storage Backend:
CarbonIntensityRepository abstractcore/factory.py mappingNew Cloud Provider:
utils/region_mapping.pyenergy/instance_profiles.pycore/config.pyApache 2.0 - See LICENSE file for details.