Sitelet https://github.com/sustainable-computing-io/kepler/blob/main/docs/user/installation.md
Skip to content

installation.md

Latest commit

 

History

History
409 lines (294 loc) · 10.2 KB

installation.md

File metadata and controls

409 lines (294 loc) · 10.2 KB
Raw

Kepler Installation Guide

This guide covers different methods to install and run Kepler (Kubernetes-based Efficient Power Level Exporter) for monitoring energy consumption metrics.

Prerequisites

  • For Local Installation: Go 1.24.0+ and sudo access for hardware sensor access
  • For Kubernetes: Kubernetes cluster (v1.20+) with kubectl configured
  • For Helm: Helm 3.0+ installed

Installation Methods

1. Helm Chart Installation (Recommended for Kubernetes)

Prerequisites for Helm

  • Helm 3.0+
  • Kubernetes cluster with kubectl configured

Install from OCI Registry (Recommended)

Install directly from the OCI registry (OCI registries cannot be added as traditional Helm repositories):

# Install specific version
helm install kepler oci://quay.io/sustainable_computing_io/charts/kepler \
  --version 0.11.1 \
  --namespace kepler \
  --create-namespace

# Install latest version (omit --version)
helm install kepler oci://quay.io/sustainable_computing_io/charts/kepler \
  --namespace kepler \
  --create-namespace

Install from Source (Development/Testing)

NOTE: This method is intended for development and testing purposes. For production deployments, use the OCI registry method above.

# Clone the repository
git clone https://github.com/sustainable-computing-io/kepler.git
cd kepler

# Install Kepler using Helm
helm install kepler manifests/helm/kepler/ \
  --namespace kepler \
  --create-namespace \
  --set namespace.create=false

Customizing the Installation

Create a values.yaml file to customize the installation:

# values.yaml
image:
  repository: quay.io/sustainable_computing_io/kepler
  tag: "v0.10.0"
  pullPolicy: IfNotPresent

resources:
  limits:
    cpu: 100m
    memory: 400Mi
  requests:
    cpu: 100m
    memory: 200Mi

tolerations:
  - operator: Exists

nodeSelector:
  kubernetes.io/os: linux

# Enable ServiceMonitor for Prometheus
serviceMonitor:
  enabled: true
  interval: 30s

Install with custom values:

# From source
helm install kepler manifests/helm/kepler/ \
  --namespace kepler \
  --create-namespace \
  --set namespace.create=false \
  --values values.yaml

# From OCI registry
helm install kepler oci://quay.io/sustainable_computing_io/charts/kepler \
  --version 0.11.1 \
  --namespace kepler \
  --create-namespace \
  --values values.yaml

Enabling GPU Power Monitoring (NVIDIA GPU Operator)

To export GPU power metrics on clusters with the NVIDIA GPU Operator, enable the experimental GPU flag. The chart then adds an nvidia-libs init container that copies libnvidia-ml.so* from the host driver path into an emptyDir, and points LD_LIBRARY_PATH at it:

helm install kepler oci://quay.io/sustainable_computing_io/charts/kepler \
  --namespace kepler \
  --create-namespace \
  --set config.experimental.gpu.enabled=true

What this changes:

  • Adds an nvidia-libs init container that copies libnvidia-ml.so* into a 200Mi emptyDir using cp -P (preserves the driver symlink chain; cp -L can exceed the size limit when leftover driver versions are present).
  • Mounts that emptyDir read-only at /usr/local/nvidia/lib64 and sets LD_LIBRARY_PATH=/usr/local/nvidia/lib64.
  • Mounts the host driver directory (default /run/nvidia/driver, overridable via daemonset.nvidia.driverPath) with DirectoryOrCreate so non-GPU nodes still schedule.

Defaults assume the standard GPU Operator layout. Override via values.yaml if needed:

config:
  experimental:
    gpu:
      enabled: true

daemonset:
  nvidia:
    driverPath: /run/nvidia/driver
    nvmlInitImage:
      repository: busybox
      tag: 1.36.1

Note: config.experimental.gpu.enabled is intentionally coupled with the chart's daemonset.nvidia.* plumbing. Enabling the binary flag without the init path (or the reverse) is not a supported split. Leave enabled: false if you do not want GPU power monitoring.

Helm Management Commands

# Check installation status
helm status kepler -n kepler

# List releases
helm list -n kepler

# Upgrade release from source
helm upgrade kepler manifests/helm/kepler/ -n kepler

# Upgrade release from OCI registry to specific version
helm upgrade kepler oci://quay.io/sustainable_computing_io/charts/kepler --version 0.11.2 -n kepler

# Upgrade to latest version from OCI registry
helm upgrade kepler oci://quay.io/sustainable_computing_io/charts/kepler -n kepler

# Uninstall
helm uninstall kepler -n kepler

2. Local Installation

Building from Source

# Clone the repository
git clone https://github.com/sustainable-computing-io/kepler.git
cd kepler

# Build Kepler
make build

# Run Kepler (requires sudo for hardware access)
sudo ./bin/kepler --config.file hack/config.yaml

Configuration

Kepler can be configured using YAML files or CLI flags. The default configuration is in hack/config.yaml:

# Run with custom configuration
sudo ./bin/kepler --config.file /path/to/your/config.yaml

# Run with CLI flags
sudo ./bin/kepler --log.level=debug --exporter.stdout

Access Points:

3. Docker Compose (Recommended for Development)

The Docker Compose setup provides a complete monitoring stack with Kepler, Prometheus, and Grafana:

cd compose/dev

# Start the complete stack
docker compose up --build -d

# View logs
docker compose logs -f kepler-dev

# Stop the stack
docker compose down --volumes

Access Points:

4. Kubernetes with Kustomize

Quick Setup with Kind

# Create a local cluster with monitoring stack
make cluster-up

# Deploy Kepler
make deploy

# Clean up
make cluster-down

Manual Kubernetes Deployment

# Deploy using kustomize
kubectl kustomize manifests/k8s | \
  sed -e "s|<KEPLER_IMAGE>|quay.io/sustainable_computing_io/kepler:latest|g" | \
  kubectl apply --server-side --force-conflicts -f -

# Check deployment status
kubectl get pods -n kepler

# Access metrics (port-forward)
kubectl port-forward -n kepler svc/kepler 28282:28282

Minimal Kubernetes Deployment (No Prometheus Operator)

If you only need the Kepler exporter and do not have Prometheus Operator installed, deploy the core resources directly and skip Prometheus-specific manifests.

# Create namespace and core RBAC/config
kubectl apply -f manifests/k8s/namespace.yaml
kubectl apply -f manifests/k8s/rbac.yaml
kubectl apply -f manifests/k8s/configmap.yaml

# Deploy DaemonSet with your desired image
sed -e "s|<KEPLER_IMAGE>|quay.io/sustainable_computing_io/kepler:latest|g" \
  manifests/k8s/daemonset.yaml | \
  kubectl apply --server-side --force-conflicts -f -

# Expose Kepler metrics service
kubectl apply -f manifests/k8s/service.yaml

This minimal path intentionally skips:

  • manifests/k8s/servicemonitor.yaml
  • manifests/k8s/prometheus-rbac.yaml

Custom Image Deployment

# Build and push custom image
make image push IMG_BASE=your-registry.com/yourorg VERSION=v1.0.0

# Deploy with custom image
make deploy IMG_BASE=your-registry.com/yourorg VERSION=v1.0.0

Verification

Check Deployment Status

# Check pods
kubectl get pods -n kepler

# Check DaemonSet
kubectl get daemonset -n kepler

# Check services
kubectl get svc -n kepler

# View logs
kubectl logs -n kepler -l app.kubernetes.io/name=kepler

Access Metrics

# Port forward to access metrics locally
kubectl port-forward -n kepler svc/kepler 28282:28282

# Test metrics endpoint
curl http://localhost:28282/metrics

Verify Metrics Collection

Look for key metrics like:

  • kepler_node_cpu_watts
  • kepler_container_cpu_watts
  • kepler_process_cpu_watts

Configuration Options

Helm Chart Values

Key configuration options in values.yaml:

# Image configuration
image:
  repository: quay.io/sustainable_computing_io/kepler
  tag: "latest"
  pullPolicy: IfNotPresent

# DaemonSet configuration
daemonset:
  hostPID: true
  securityContext:
    privileged: true

# Resource limits
resources:
  limits:
    cpu: 100m
    memory: 400Mi
  requests:
    cpu: 100m
    memory: 200Mi

# Node scheduling
tolerations:
  - operator: Exists

nodeSelector:
  kubernetes.io/os: linux

# Monitoring
serviceMonitor:
  enabled: true
  interval: 30s
  scrapeTimeout: 10s

Environment-Specific Settings

  • Development: Use fake CPU meter when RAPL unavailable
  • Production: Ensure nodes have Intel RAPL support
  • Cloud: May need different privilege configurations

Troubleshooting

Common Issues

  1. Permission Denied: Ensure privileged security context is enabled
  2. No Metrics: Check if nodes support Intel RAPL sensors
  3. Pod Crashes: Review logs for hardware access issues
  4. ServiceMonitor Not Found: Ensure Prometheus Operator is installed, or use the minimal deployment section above

Debug Commands

# Check pod logs
kubectl logs -n kepler -l app.kubernetes.io/name=kepler

# Describe pod for events
kubectl describe pod -n kepler -l app.kubernetes.io/name=kepler

# Check node hardware
kubectl exec -n kepler -it <pod-name> -- ls /sys/class/powercap/intel-rapl

# Test with fake meter (development)
helm upgrade kepler manifests/helm/kepler/ -n kepler \
  --set env.KEPLER_FAKE_CPU_METER=true

Getting Help

Next Steps

After successful installation:

  1. Set up Prometheus: Configure scraping of Kepler metrics
  2. Install Grafana: Use pre-built dashboards for visualization
  3. Configure Alerts: Set up energy consumption alerts
  4. Explore Metrics: Learn about available energy metrics
  5. Optimize Workloads: Use insights to improve energy efficiency