Kepler

Kepler (Kubernetes-based Efficient Power Level Exporter) is a Prometheus exporter that measures energy consumption metrics at the container, pod, and node level in Kubernetes clusters.

🚀 Major Rewrite: Kepler (0.10.0 and above)

Important Notice: Starting with version 0.10.0, Kepler has undergone a complete ground-up rewrite. This represents a significant architectural improvement while maintaining the core mission of accurate energy consumption monitoring for cloud-native workloads.

📢 Read the full announcement: CNCF Slack Announcement

✨ What's New in the Rewrite

Enhanced Performance & Accuracy:

• Dynamic detection of Nodes' RAPL zones - no more hardcoded RAPL zones
• More accurate power attribution based on active CPU usage (no more idle/dynamic for workloads)
• Improved VM, Container, and Pod detection with more meaningful label values
• Significantly reduced resource usage compared to old Kepler

Reduced Security Requirements:

• Requires only readonly access to host /proc and /sys
• No more CAP_SYSADMIN or CAP_BPF capabilities required
• Much fewer privileges than previous versions

Modern Architecture:

• Service-oriented design with clean separation of concerns
• Thread-safe operations throughout the codebase
• Graceful shutdown handling with proper resource cleanup
• Comprehensive error handling with structured logging

Current Limitations:

• Supports RAPL/powercap framework, with experimental support for HWMon, GPU (NVIDIA), and platform power (Redfish BMC)

📚 Migration & Legacy Support

For New Users: Use the current version (0.10.0+) for the best experience and latest features.

For Existing Users: If you need to continue using the old version:

• Pin your deployment to version 0.9.0 (final legacy release)
• Access the old codebase in the archived branch
• Important: The legacy version (0.9.x and earlier) is now frozen - no bug fixes or feature requests will be accepted for the old version

Migration Note: Please review the new configuration format and deployment methods below when upgrading to 0.10.0+.

🚀 Getting Started

📖 For comprehensive installation instructions, troubleshooting, and advanced deployment options, see our Installation Guide

⚡ Quick Start (Kubernetes with Helm)

# 1. Install Kepler using Helm from OCI registry
helm install kepler oci://quay.io/sustainable_computing_io/charts/kepler \
  --namespace kepler \
  --create-namespace

# Wait for Kepler pods to be running
kubectl wait --for=condition=ready --timeout=120s pod -n kepler --all

# 2. Verify installation
kubectl get pods -n kepler

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

# Test metrics endpoint
curl http://localhost:28282/metrics | grep kepler_node_cpu_watts

📋 For Production Deployments: Consider using the Kepler Operator for advanced lifecycle management and operational capabilities.

Next Steps:

To ensure Kepler is working correctly and to visualize the metrics:

• Verify Metrics Collection - Verify power consumption metrics are being collected
• Configuration Options - Customize Kepler deployment
• Helm Updates & Management - Learn how to upgrade and manage Kepler with Helm

Need Help?

• Installation Guide - Detailed prerequisites, configuration options, and installation steps
• Metrics Documentation - Available metrics and their descriptions

🔧 Other Installation Methods

Choose your preferred method:

# 💻 Local Development
make build && sudo ./bin/kepler

# ✨ Docker Compose (with Prometheus & Grafana)
cd compose/dev && docker compose up -d

# 🐳 Kubernetes with Kustomize
git clone https://github.com/sustainable-computing-io/kepler.git
cd kepler && git checkout v0.11.4 # pin to a release tag, see note below
kubectl kustomize manifests/k8s | \
  sed -e "s|<KEPLER_IMAGE>|quay.io/sustainable_computing_io/kepler:v0.11.4|g" | \
  kubectl apply --server-side --force-conflicts -f -

⚠️ Important: Always check out a matching release tag (rather than main) before applying manifests from manifests/k8s, and set <KEPLER_IMAGE> to that same version. Manifests on main can reference features not yet present in the last published image (for example, the /probe/livez and /probe/readyz endpoints added for liveness/readiness probes) — mixing a main manifest with an older image can make the container fail its liveness probe and crash-loop. See the Releases page for available tags.

📖 Documentation

User Documentation

• Installation Guide - Detailed installation instructions for all deployment methods
• Configuration Guide - Configuration options and examples
• Metrics Documentation - Available metrics and their descriptions

Developer Documentation

• Architecture Documentation - Complete architectural documentation including design principles, system components, data flow, concurrency model, and deployment patterns
• Power Attribution Guide - How Kepler measures and attributes power consumption
• Developer Documentation - Contributing guidelines and development workflow

For more detailed documentation, please visit the official Kepler documentation.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For more detailed information about contributing to this project, please refer to our CONTRIBUTING.md file.

Gen AI policy

Our project adheres to the Linux Foundation's Generative AI Policy, which can be viewed at https://www.linuxfoundation.org/legal/generative-ai.

⭐ Star History

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSES for details.