GreenKube Logo GreenKube

Measure, understand, and reduce the carbon footprint of your Kubernetes infrastructure. Make your cloud operations both cost-effective and environmentally responsible.

GreenKube is an open-source tool designed to help DevOps, SRE, and FinOps teams navigate the complexity of sustainability reporting (CSRD) and optimize their cloud costs (FinOps) through better energy efficiency (GreenOps).

License: Apache 2.0 GitHub Stars Build in Public

🎯 Mission

The EU’s Corporate Sustainability Reporting Directive (CSRD) requires companies to report the carbon footprint of their value chain—including cloud services (Scope 3). GreenKube addresses this urgent need by providing tools to:

  1. Estimate the energy consumption and CO₂e emissions of each Kubernetes workload.
  2. Report these metrics in a format aligned with regulatory requirements (ESRS E1).
  3. Optimize infrastructure to simultaneously reduce cloud bills and environmental impact.

✨ Features (Version 0.2.2)

📊 Dashboard & Visualization

📈 Comprehensive Resource Monitoring

🎯 Optimization & Reporting

🔧 Infrastructure & Deployment

📦 Dependencies

The chart requires the following services to be available in the cluster:

GreenKube uses service auto‑discovery to locate these services automatically. If they are deployed in non‑standard namespaces or with custom names, auto‑discovery may fail. In that case, set the service URLs manually in values.yaml (see the prometheus.url and opencost.url fields).

🚀 Installation & Usage

The recommended way to install GreenKube is via the official Helm chart.

1. Add the GreenKube Helm Repository

First, add the GreenKube chart repository to your local Helm setup:

helm repo add greenkube https://GreenKubeCloud.github.io/GreenKube
helm repo update

2. Configure Your Installation

Create a file named my-values.yaml to customize your deployment:

secrets:
  # Get your API token from https://www.electricitymaps.com/
  # Optional: without it, GreenKube uses a default carbon intensity
  # value (configurable via config.defaultIntensity) for all zones.
  electricityMapsToken: "YOUR_API_TOKEN_HERE"

# Uncomment to manually set your Prometheus URL
# (If left empty, GreenKube will try to auto-discover it)
# config:
#   prometheus:
#     url: "http://prometheus-k8s.monitoring.svc.cluster.local:9090"

Note: GreenKube works without an Electricity Maps token. When no token is provided, a default carbon intensity value (config.defaultIntensity, default: 500 gCO₂e/kWh) is used for all zones. This gives approximate results. For accurate, zone-specific carbon data, provide a token from Electricity Maps.

Install the Chart

Install the Helm chart into a dedicated namespace (e.g., greenkube):

helm install greenkube greenkube/greenkube \
  -f my-values.yaml \
  -n greenkube \
  --create-namespace

This deploys GreenKube with the collector, the API server, and the web dashboard — all in a single image.

🎮 Quick Start with Demo Mode

Want to explore GreenKube with realistic sample data? Deploy the demo mode as a standalone pod:

# 1. Deploy GreenKube demo as a one-time pod
kubectl run greenkube-demo \
  --image=greenkube/greenkube:0.2.2 \
  --restart=Never \
  --command -- greenkube demo --no-browser --port 9000

# 2. Wait for it to start (about 10 seconds)
kubectl wait --for=condition=Ready pod/greenkube-demo --timeout=30s

# 3. Port-forward to access the dashboard
kubectl port-forward pod/greenkube-demo 9000:9000

# 4. Open http://localhost:9000 in your browser

This demo mode:

Demo options:

# Generate 14 days of data instead of 7
kubectl run greenkube-demo --image=greenkube/greenkube:0.2.2 --restart=Never \
  --command -- greenkube demo --no-browser --days 14 --port 9000

# Clean up when done
kubectl delete pod greenkube-demo

Perfect for:

🖥️ Web Dashboard

GreenKube ships with a built-in web dashboard (SvelteKit SPA served by the API). Once deployed, access it via port-forward:

kubectl port-forward svc/greenkube-api 8000:8000 -n greenkube

Then open http://localhost:8000 in your browser.

The dashboard includes:

🎨 Dashboard Features

🔌 API Reference

The API is available at /api/v1 and serves both JSON endpoints and the web dashboard.

Endpoint Description
GET /api/v1/health Health check and version
GET /api/v1/version Application version
GET /api/v1/config Current configuration
GET /api/v1/metrics?namespace=&last=24h Per-pod metrics
GET /api/v1/metrics/summary?namespace=&last=24h Aggregated summary
GET /api/v1/metrics/timeseries?granularity=day&last=7d Time-series data
GET /api/v1/namespaces List of active namespaces
GET /api/v1/nodes Cluster node inventory
GET /api/v1/recommendations?namespace= Optimization recommendations

Interactive API docs are available at /api/v1/docs (Swagger UI).

API Examples

# Get a health check
curl http://localhost:8000/api/v1/health
# {"status":"ok","version":"0.2.2"}

# Get metrics for the last 24 hours
curl "http://localhost:8000/api/v1/metrics?last=24h"

# Get metrics summary for a specific namespace
curl "http://localhost:8000/api/v1/metrics/summary?namespace=default&last=7d"
# {"total_co2e_grams":142.5,"total_embodied_co2e_grams":12.3,"total_cost":0.87,...}

# Get hourly timeseries data for the last 7 days
curl "http://localhost:8000/api/v1/metrics/timeseries?granularity=hour&last=7d"

# Get optimization recommendations
curl "http://localhost:8000/api/v1/recommendations?namespace=production"

📈 Running Reports & Getting Recommendations

The primary way to interact with GreenKube is by using kubectl exec to run commands inside the running pod.

1. Find your GreenKube pod:

kubectl get pods -n greenkube

(Look for a pod named something like greenkube-7b5…)

2. Run an on-demand report:

# Replace <pod-name> with the name from the previous step
kubectl exec -it <pod-name> -n greenkube -- bash

3. Run a report:

greenkube report --daily

See the doc or greenkube report --help to see more options.

4. Get optimization recommendations:

greenkube recommend

🏗️ Architecture Summary

GreenKube follows a clean, hexagonal architecture with strict separation between core business logic and infrastructure adapters.

Core Components

Collectors (Input Adapters):

Processing Pipeline:

Business Logic:

Storage (Output Adapters):

API & Presentation:

Data Flow

  1. Collection Phase (async/concurrent): 
    Prometheus → CPU, memory, network, disk metrics
Kubernetes → Node metadata, pod resource requests
OpenCost → Cost allocation data
  2. Processing Phase: 
    Raw metrics → Energy estimation (Joules per pod)
Node metadata → Cloud zone mapping
Historical data → Node state reconstruction
  3. Calculation Phase: 
    Energy + Grid intensity + PUE → CO₂e emissions
Metrics + Cost data → Combined metrics
  4. Analysis Phase: 
    Combined metrics → Recommendations engine
Time-series data → Trend analysis
  5. Storage & Presentation: 
    Combined metrics → Database (Postgres/SQLite/ES)
Database → API → Web Dashboard
API → CLI reports/exports

Key Design Principles

🔬 How Energy & CO₂e Estimation Works

GreenKube’s estimation pipeline converts raw Kubernetes metrics into actionable carbon data in four steps:

  1. Collect CPU usage — Prometheus provides per-pod CPU utilisation in millicores over each collection interval.
  2. Map to power — Each node’s instance type is matched to a power profile (min/max watts per vCPU) derived from SPECpower benchmarks and the Cloud Carbon Footprint coefficient database. The power draw is linearly interpolated between min watts (idle) and max watts (100 % utilisation).
  3. Apply PUE — The estimated power is multiplied by the Power Usage Effectiveness factor for the cloud provider’s data centre (e.g. 1.135 for AWS, 1.10 for GCP).
  4. Convert to CO₂e — Energy (kWh) is multiplied by the grid carbon intensity of the node’s geographic zone. When available, real-time intensity is fetched from the Electricity Maps API; otherwise a configurable default is used.

Embodied emissions are estimated separately via the Boavizta API, which models the manufacturing footprint of cloud instances amortised over their expected lifespan.

For provider-specific coefficients and the full derivation, see docs/power_estimation_methodology.md.

📋 Changelog

See CHANGELOG.md for a full version history and the GitHub Releases page for published releases.

🤝 Contributing

GreenKube is a community-driven project, and we welcome all contributions! Check out our CONTRIBUTING.md file to learn how to get involved.

Development Setup

# Clone and install
git clone https://github.com/GreenKubeCloud/GreenKube.git
cd GreenKube
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,test]"
pre-commit install

# Run the tests
pytest

# Start the API locally (uses SQLite by default)
DB_TYPE=sqlite greenkube-api

# Run the frontend
cd frontend && npm install && npm run dev

📄 Licence

This project is licensed under the Apache 2.0 License. See the LICENSE file for more details.

This site is open source. Improve this page.