Skip to content
GreenKube

Quick Start

This guide will have GreenKube up and running in your cluster in under 5 minutes.

Prerequisites

Section titled “Prerequisites”

Before you begin, make sure you have:

  • ✅ A running Kubernetes cluster (Minikube, EKS, GKE, AKS, etc.)
  • ✅ Helm 3 installed (install guide)
  • ✅ kubectl configured to access your cluster
  • ✅ Prometheus deployed in your cluster (e.g., via kube-prometheus-stack)
  • ✅ OpenCost deployed for cost data (optional but recommended)

Try the Demo First (No Cluster Required)

Section titled “Try the Demo First (No Cluster Required)”

Want to explore GreenKube without any infrastructure? Start with Demo Mode — it loads 7 days of realistic data for 22 pods across 5 namespaces, with carbon emissions, costs, and recommendations pre-loaded.

The fastest way to try GreenKube. Only Docker is required — no Kubernetes, no Prometheus, no setup.

Terminal window
docker run --rm -p 9000:9000 \
  greenkube/greenkube:0.2.3 \
  demo --no-browser --port 9000

Open http://localhost:9000 in your browser. Press Ctrl+C to stop.

Installation

Section titled “Installation”

  1. Add the Helm repository and install

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

    This deploys the data collector, REST API, web dashboard, and a PostgreSQL database — all in one command.

  2. Wait for pods to be ready

    Terminal window
    kubectl get pods -n greenkube -w

    You should see:

    NAME                         READY   STATUS    RESTARTS   AGE
    greenkube-7b5f8c9d6-x2k4p   2/2     Running   0          30s
    greenkube-postgres-0         1/1     Running   0          30s

  3. Access the dashboard

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

    Open http://localhost:8000 in your browser.

  4. (Optional) Add an Electricity Maps token

    For accurate, region-specific carbon data instead of the default 500 gCO₂e/kWh:

    Terminal window
    helm upgrade greenkube greenkube/greenkube \
      -n greenkube \
      --set secrets.electricityMapsToken="YOUR_TOKEN_HERE"

    Get a free token at electricitymaps.com.

  5. Run your first report

    Terminal window
    GREENKUBE_POD=$(kubectl get pods -n greenkube \
      -l app.kubernetes.io/name=greenkube,app.kubernetes.io/component=app \
      -o jsonpath='{.items[0].metadata.name}')
    

    kubectl exec -it $GREENKUBE_POD -n greenkube -- greenkube report --daily
    kubectl exec -it $GREENKUBE_POD -n greenkube -- greenkube recommend

What You’ll See

Section titled “What You’ll See”
  • Dashboard — KPI cards showing total CO₂ emissions, costs, energy consumption, and active pods. Time-series charts and namespace breakdown.
  • Metrics — Interactive table with per-pod metrics: energy (CPU-based), cost, CPU, memory, network, disk, storage, and restarts.
  • Nodes — Cluster node inventory with CPU/memory capacity, hardware profiles, cloud provider info.
  • Recommendations — Actionable suggestions to reduce costs and emissions (zombie pods, rightsizing, autoscaling).
  • Settings — Current configuration, API health, version info, database connection details.

Next Steps

Section titled “Next Steps”