Getting Started on Joulie

Core Concepts

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

Before installing Joulie, understand the control model.

Problem Joulie addresses

Clusters running AI/scientific workloads need better power control:

reduce energy use and power spikes,
keep workload performance predictable,
provide a path to greener operation (power envelope and carbon-aware strategies).

Joulie is currently a PoC focused on Kubernetes-native control loops and simulation.

Main components

Operator (cmd/operator): cluster-level policy brain
- decides desired node power profile/cap assignments
- writes desired state as NodePowerProfile
Agent (cmd/agent): node-level actuator
- reads desired state and telemetry configuration
- enforces power controls (CPU now, GPU path planned)
- exports metrics/status
Simulator (simulator/): digital-twin execution environment
- keeps scheduling real, simulates telemetry/control behavior
- enables repeatable experiments without requiring real hardware writes

Key CRDs

NodePowerProfile (joulie.io/v1alpha1)
- desired node policy state (performance / eco, optional power cap)
TelemetryProfile (joulie.io/v1alpha1)
- where telemetry/control inputs come from (host, http, …), and how controls are sent

Policy states and intent

Node supply is represented through joulie.io/power-profile:

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/mbunino/joulie/joulie \
 --version <version> \
 -n joulie-system \
 --create-namespace \
 -f values/joulie.yaml

Label nodes managed by the operator

Important: Joulie will only target nodes with a specific label, and ignore all the others. By default, install does not auto-select nodes. Default expected selector value is:

Pod Compatibility for Joulie

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

Joulie uses Kubernetes scheduling constraints as the single source of truth for workload placement intent.

Power profile supply is exposed on node label:

joulie.io/power-profile=performance
joulie.io/power-profile=eco
joulie.io/draining=true|false (independent transition flag)

Workload behavior:

performance workload (recommended): require joulie.io/power-profile NotIn ["eco"]
eco workload: require joulie.io/power-profile=eco
unconstrained workload: no power-profile affinity, can run on either profile

Best-effort Pod (unconstrained, starting point)

This is the default and recommended starting spec. Do not set power-profile affinity: Kubernetes can schedule the pod on either eco or performance nodes.

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.