Getting Started on Joulie

Core Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Before installing Joulie, understand the control model.

What Joulie is

Joulie is a Kubernetes-native energy management system that uses per-node digital twins to optimize data center power consumption.

It continuously ingests telemetry from every node (CPU/GPU power draw via RAPL and NVML/DCGM, read from Prometheus as the OpenTelemetry hardware metrics hw.energy and hw.power or as Kepler energy counters, and per-pod resource utilization via cAdvisor) to maintain an up-to-date model of each node’s thermal and power state.

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

This page is the fastest path to run Joulie. For conceptual context first, read Core Concepts.

Prerequisites

Kubernetes cluster with worker nodes
Node Feature Discovery (NFD) deployed
Optional for real enforcement: nodes exposing writable power interfaces
- RAPL power limit files, or
- cpufreq sysfs interfaces
Prometheus, for measured node power. The chart reads node power from Prometheus by default (NODE_POWER_SOURCE=prometheus): it expects Prometheus at http://prometheus-operated.monitoring:9090 with its OTLP receiver on (--web.enable-otlp-receiver), receiving hw.energy or hw.power for each node. Without that data every node reads 0 W, with source prometheus-no-data.
- values/prometheus-grafana.yaml configures kube-prometheus-stack this way (Prometheus settings).
- examples/11-otel-collector-bridge converts Kepler, dcgm-exporter and AMD device-metrics-exporter metrics into those names.
- To run without it, set controllerManager.env.NODE_POWER_SOURCE=static (0 W for every node).

Install from release (recommended)

Install directly from OCI chart release:

Pod Compatibility for Joulie

Mon, 01 Jan 0001 00:00:00 +0000

Joulie uses a single pod annotation to express workload placement intent:

joulie.io/workload-class: performance | standard

The scheduler extender reads this annotation and steers pods accordingly. No node affinity rules are needed.

Workload classes

Class	Behavior
`performance`	Must run on full-power nodes. The extender hard-rejects eco nodes.
`standard`	Default. Can run on any node. Adaptive scoring steers toward eco when performance nodes are congested.

If no annotation is present, the extender treats it as standard.

Agent Runtime Modes

Mon, 01 Jan 0001 00:00:00 +0000

The chart runs the agent in one of three modes, or not at all (agent.mode):

`agent.mode`	Pods	Use
`daemonset` (default)	one pod per managed node (`charts/joulie/templates/agent-daemonset.yaml`)	real hardware
`pool`	a StatefulSet whose pods each run many logical per-node agents (`agent-statefulset.yaml`)	KWOK experiments over the simulator’s HTTP API
`emulated`	one Deployment per node of the simulated cluster (`agent-emulated.yaml`), reading that node’s emulated `/sys` and GPU tools	the simulated cluster
`none`	no agent

DaemonSet mode (real hardware)

Required runtime settings

securityContext.privileged: true
Host mount:
- host path /sys -> container path /host-sys
Env:
- NODE_NAME from spec.nodeName
- AGENT_MODE=daemonset (default)
- optional RECONCILE_INTERVAL (default 20s)
- optional SIMULATE_ONLY=true (skip host writes, log requested actions)
- optional METRICS_ADDR (default :8080)

Pool mode (KWOK / simulation)

Pool mode preserves per-node semantics but shards logical node controllers across replicas.

Configuration Reference

Mon, 01 Jan 0001 00:00:00 +0000

Complete reference for all Joulie environment variables. These are set via Helm values or directly in the Deployment/DaemonSet manifests.

Defaults listed below are the code defaults. The Helm chart (charts/joulie/values.yaml) overrides some of them: notably, the controller manager NODE_SELECTOR defaults to joulie.io/managed=true in the chart even though the code default is node-role.kubernetes.io/worker.

Booleans. The agent, the controller manager and the simulator read every on/off variable the same way: true, 1, yes or on, and false, 0, no or off, in any case, with surrounding spaces ignored. Unset or empty means the default. Any other value keeps the default and logs one warning naming the variable, so a typo never flips a switch. The exceptions are SIM_OTEL_FILE_METRICS, OTEL_SDK_DISABLED and fakesmi’s HWEMU_UNPRIVILEGED, whose rows say how they are read.

Upgrading

Mon, 01 Jan 0001 00:00:00 +0000

What to check when you upgrade a Joulie installation from v0.2 to v0.3. Go through the list before running helm upgrade.

Before the upgrade

Apply the new CRDs. helm upgrade never updates CRDs, and the API server prunes every field the installed CRD does not know, such as the governor fields of NodeTwin and NodeHardware. Apply them first:
```
kubectl apply -f charts/joulie/crds/
```
Without a checkout, take them from the release chart: helm pull oci://registry.cern.ch/joulie/joulie --version <version> --untar --untardir /tmp/joulie-chart, then kubectl apply -f /tmp/joulie-chart/joulie/crds/.