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, per-pod resource utilization via cAdvisor, and optional energy counters from Kepler) to maintain an up-to-date model of each node’s thermal and power state.

These per-node digital twins drive two outcomes:

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

Install from release (recommended)

Install directly from OCI chart release:

helm upgrade --install joulie oci://registry.cern.ch/joulie/joulie \
 --version <version> \
 -n joulie-system \
 --create-namespace \
 -f values/joulie.yaml

Charts, images and the kubectl plugin used to be published under registry.cern.ch/mbunino/joulie. Every tag published there up to 0.2.0 was copied to registry.cern.ch/joulie with the same digest, and later releases are published only to registry.cern.ch/joulie. If your values file sets an image.repository or you pull latest, point it at the new path.

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 agent supports two runtime modes:

daemonset: real-hardware mode, one pod per real node.
pool: simulation mode, one pod hosts many logical per-node controllers.

Chart templates:

charts/joulie/templates/agent-daemonset.yaml
charts/joulie/templates/agent-statefulset.yaml

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.

Images

The chart values agent.image.tag, controllerManager.image.tag and schedulerExtender.image.tag (and image.tag in the simulator chart) default to empty, which pulls the chart’s appVersion. A chart installed from oci://registry.cern.ch/joulie carries the version it was released with, so it runs the images of that release. A chart installed from a checkout has appVersion: latest and runs the newest stable release. Set a tag only to run other images, for example your own build.