⚙️ Configuring Kepler with Custom ConfigMaps

October 14, 2025 · View on GitHub

This guide explains how to customize Kepler's configuration using the additionalConfigMaps feature in the PowerMonitor custom resource.

📋 Overview

The Kepler Operator allows you to customize Kepler's behavior by providing additional configuration through Kubernetes ConfigMaps. When you reference ConfigMaps in your PowerMonitor CR, the operator automatically:

Merges your custom configuration with the default Kepler configuration
Updates the Kepler DaemonSet with the new configuration
Automatically triggers a rollout when the ConfigMap changes

✅ Prerequisites

Kepler Operator installed in your cluster
PowerMonitor CR deployed
Access to create ConfigMaps in the namespace where Kepler is deployed (default: power-monitor)

🚀 Step-by-Step Configuration

📝 Step 1: Create a ConfigMap with Your Custom Configuration

Create a ConfigMap containing your Kepler configuration in a file named config.yaml. The ConfigMap must exist in the same namespace as the PowerMonitor deployment.

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-kepler-config
  namespace: power-monitor
data:
  config.yaml: |
    dev:
      fake-cpu-meter:
        enabled: false

Apply the ConfigMap:

kubectl apply -f my-kepler-config.yaml

🔗 Step 2: Reference the ConfigMap in Your PowerMonitor CR

Update your PowerMonitor custom resource to reference the ConfigMap you created:

apiVersion: kepler.system.sustainable.computing.io/v1alpha1
kind: PowerMonitor
metadata:
  name: power-monitor
spec:
  kepler:
    config:
      logLevel: info
      additionalConfigMaps:
        - name: my-kepler-config
    deployment:
      security:
        mode: none

Apply the updated PowerMonitor CR:

kubectl apply -f power-monitor.yaml

✔️ Step 3: Verify the Configuration

The operator will automatically reconcile the DaemonSet with your new configuration. You can monitor the rollout:

# Check PowerMonitor status
kubectl get powermonitor power-monitor

# Watch DaemonSet rollout
kubectl rollout status daemonset/power-monitor -n power-monitor

# Verify the ConfigMap is mounted
kubectl describe daemonset power-monitor -n power-monitor

💡 Configuration Examples

📤 Example 1: Enabling the Stdout Exporter

apiVersion: v1
kind: ConfigMap
metadata:
  name: kepler-stdout-config
  namespace: power-monitor
data:
  config.yaml: |
    exporter:
      stdout:
        enabled: true

📊 Example 2: Customizing Prometheus Exporter Settings

apiVersion: v1
kind: ConfigMap
metadata:
  name: kepler-prometheus-config
  namespace: power-monitor
data:
  config.yaml: |
    exporter:
      prometheus:
        enabled: true
        debugCollectors:
          - go

🔧 Example 3: Enabling Development Features

Enable fake CPU meter for testing environments:

apiVersion: v1
kind: ConfigMap
metadata:
  name: kepler-dev-config
  namespace: power-monitor
data:
  config.yaml: |
    dev:
      fake-cpu-meter:
        enabled: true

🐛 Example 4: Enabling pprof Debug Endpoints

apiVersion: v1
kind: ConfigMap
metadata:
  name: kepler-pprof-config
  namespace: power-monitor
data:
  config.yaml: |
    debug:
      pprof:
        enabled: true

🔬 Example 5: Enabling Experimental Redfish BMC Monitoring

⚠️ EXPERIMENTAL FEATURE - See Redfish Monitoring Guide

Enable platform-level power monitoring via Redfish BMC API:

apiVersion: v1
kind: ConfigMap
metadata:
  name: enable-redfish
  namespace: power-monitor
data:
  config.yaml: |
    experimental:
      platform:
        redfish:
          enabled: true
          configFile: /etc/kepler/secrets/redfish/redfish.yaml
          httpTimeout: 5s

Important Notes:

This feature is experimental and may change in future versions
Requires a Secret containing BMC credentials (not shown here)
The configFile must point to a mounted Secret path
See the complete Redfish Monitoring Guide for full setup instructions

When to use:

You need platform-level power consumption (PSU, cooling, storage)
Running on servers with Redfish-enabled BMCs
Want to complement CPU-only RAPL monitoring
Need power data when running Kepler in VMs

🗂️ Using Multiple ConfigMaps

You can reference multiple ConfigMaps to organize your configuration. The operator merges them in the order specified:

spec:
  kepler:
    config:
      additionalConfigMaps:
        - name: my-kepler-config
        - name: kepler-stdout-config
        - name: kepler-prometheus-config
        - name: kepler-dev-config
        - name: kepler-pprof-config
        - name: enable-redfish

📌 Note: If there are conflicting settings across multiple ConfigMaps, the later ConfigMap in the list takes precedence.

💡 Tip: Settings controlled by spec.kepler.config still override the merged ConfigMap values. Use additionalConfigMaps only for fields that are not exposed in the CR spec.

🔄 Updating Configuration

To update Kepler's configuration:

Update the ConfigMap:

kubectl edit configmap my-kepler-config -n power-monitor

The operator automatically detects the change and triggers a DaemonSet rollout with the updated configuration.

Monitor the rollout:

kubectl rollout status daemonset/power-monitor -n power-monitor

🔍 Troubleshooting

❌ ConfigMap Not Found

If you see an error like configMap my-kepler-config not found in power-monitor namespace:

Verify the ConfigMap exists:

kubectl get configmap my-kepler-config -n power-monitor

Ensure the namespace matches your PowerMonitor deployment namespace
Check the ConfigMap name is correctly spelled in the PowerMonitor CR

⚠️ Configuration Not Applied

If your configuration changes aren't taking effect:

Check the PowerMonitor status for reconciliation errors:
```
kubectl describe powermonitor power-monitor
```

Verify the ConfigMap has the correct structure with a config.yaml key:

kubectl get configmap my-kepler-config -n power-monitor -o yaml

Check the operator logs:

# For Kubernetes (Helm installation)
kubectl logs -n kepler-operator deployment/kepler-operator-controller

# For OpenShift (OperatorHub installation)
kubectl logs -n openshift-operators deployment/kepler-operator-controller

🔁 DaemonSet Not Rolling Out

If the DaemonSet doesn't roll out after updating the ConfigMap:

Check if the ConfigMap hash annotation changed:

kubectl get daemonset power-monitor -n power-monitor -o jsonpath='{.spec.template.metadata.annotations}'

Manually trigger a rollout:

kubectl rollout restart daemonset/power-monitor -n power-monitor

⭐ Best Practices

Use Descriptive Names: Name your ConfigMaps descriptively (e.g., kepler-production-config, kepler-dev-settings)
Test Before Production: Test configuration changes in a development environment first
Monitor Changes: Watch the DaemonSet rollout after making configuration changes
Validate YAML: Ensure your config.yaml is valid YAML before creating the ConfigMap
Document Changes: Add comments or annotations to explain why specific configurations were chosen
Use Multiple ConfigMaps: Separate concerns by using different ConfigMaps for different aspects (e.g., metrics, performance, debugging)

PowerMonitor Guide - Complete PowerMonitor configuration guide
PowerMonitor API Reference
Kepler Configuration Reference
Kepler Documentation

💬 Additional Support

For more information or help:

Visit the Kepler Operator repository
File an issue on GitHub