Installation

Installation Methods

Helm (Recommended)

Helm Chart Installation

The recommended way to deploy GreenKube in a production Kubernetes cluster.

1. Add the Helm repository

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

2. Create a values file

   Create my-values.yaml to customize your deployment:

   my-values.yaml

   secrets:
     # Get your API token from https://www.electricitymaps.com/
     electricityMapsToken: "YOUR_TOKEN_HERE"
   
   config:
     cloudProvider: aws  # aws, gcp, azure, ovh, scaleway
     defaultZone: FR     # Fallback carbon zone (ISO 3166-1)
   
     # Uncomment to manually set Prometheus URL
     # prometheus:
     #   url: "http://prometheus-k8s.monitoring.svc.cluster.local:9090"
   
     # Uncomment to manually set OpenCost URL
     # opencost:
     #   url: "http://opencost.opencost.svc.cluster.local:9003"
   
     db:
       type: postgres  # postgres (recommended), sqlite, elasticsearch
   
   postgres:
     enabled: true
     persistence:
       enabled: true
       size: 5Gi

3. Install the chart

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

4. Verify the installation

   kubectl get all -n greenkube

Upgrading

helm repo update
helm upgrade greenkube greenkube/greenkube \
  -f my-values.yaml \
  -n greenkube

Uninstalling

helm uninstall greenkube -n greenkube
kubectl delete namespace greenkube

From Source

Installation from Source

For development or contributing to GreenKube.

1. Clone the repository

   git clone https://github.com/GreenKubeCloud/GreenKube.git
   cd GreenKube

2. Create a virtual environment

   python -m venv .venv
   source .venv/bin/activate

3. Install dependencies

   pip install -e '.[test,dev]'

4. Run tests

   pytest

5. Start the API server

   greenkube-api

Prerequisites

Required Services

Service	Purpose	How to Install
Prometheus	Metrics collection (CPU, memory, network, disk)	kube-prometheus-stack
OpenCost	Cost allocation data	OpenCost Helm Chart

Service Auto-Discovery

GreenKube automatically discovers Prometheus and OpenCost services in your cluster by probing common service names and namespaces. If auto-discovery fails (custom naming or namespace), set the URLs manually:

# In your values.yaml
config:
  prometheus:
    url: "http://prometheus-server.monitoring.svc.cluster.local:9090"
  opencost:
    url: "http://opencost.opencost.svc.cluster.local:9003"

Helm Chart Components

The Helm chart deploys the following resources:

Resource	Description
Deployment	GreenKube application (collector + API + dashboard)
Service	Exposes the API on port 8000
ConfigMap	Non-sensitive configuration
Secret	API tokens and database credentials
ServiceAccount	Identity for pod RBAC
ClusterRole	Read access to nodes, pods, namespaces
ClusterRoleBinding	Binds ClusterRole to ServiceAccount
StatefulSet	PostgreSQL database (if enabled)
PersistentVolumeClaim	Database storage (if persistence enabled)
Job (post-install hook)	Database schema initialization

Resource Requirements

Minimum

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Recommended (Production)

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: 1000m
    memory: 1Gi

Networking

The API server listens on port 8000 by default. Access methods:

• Port-forward (development): kubectl port-forward svc/greenkube-api 8000:8000 -n greenkube
• LoadBalancer: Set service.type: LoadBalancer in values.yaml
• Ingress: Configure an Ingress resource pointing to the service
• NodePort: Set service.type: NodePort for direct node access