Architecture on Joulie

CRD and Policy Model

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

This page defines Joulie’s core contract:

demand comes from pod scheduling constraints,
supply is exposed by node power-profile labels,
desired state is published through NodePowerProfile.

APIs

Group/version:

joulie.io/v1alpha1

CRDs:

NodePowerProfile (nodepowerprofiles, cluster-scoped)
TelemetryProfile (telemetryprofiles, cluster-scoped)

CRD definitions live in:

config/crd/bases/joulie.io_nodepowerprofiles.yaml
config/crd/bases/joulie.io_telemetryprofiles.yaml

Demand model (workloads)

Workload class is inferred from Kubernetes scheduling constraints on key:

joulie.io/power-profile

Classification:

performance demand:
- pod requires joulie.io/power-profile=performance
eco demand:
- pod requires joulie.io/power-profile=eco
general demand:
- no explicit power-profile requirement (unconstrained)

Classification source is affinity/selector, not a custom intent label.

Joulie Operator

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

The operator is Joulie’s cluster-level decision engine.

It does not write host power interfaces directly. Instead, it decides desired node states and publishes them through Kubernetes objects and labels.

Responsibilities

At each reconcile tick, the operator:

selects eligible managed nodes,
classifies workload demand from pod scheduling constraints,
runs a policy algorithm to compute a plan,
applies transition guards for safe downgrades,
writes desired node targets (NodePowerProfile) and node supply labels.

The agent then enforces those targets node-by-node.

Joulie Agent

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

The agent is Joulie’s node-side enforcement component.

It consumes desired state and applies node-local controls through configured backends.

Responsibilities

At each reconcile tick, the agent:

identifies its node scope (single node in daemonset mode, sharded set in pool mode),
reads desired target (NodePowerProfile) for each owned node,
reads telemetry/control routing (TelemetryProfile),
applies controls (host or HTTP),
exports metrics and status.

Inputs and outputs

Inputs:

NodePowerProfile for desired profile/cap
TelemetryProfile for source/control backend selection
node capability hints (for example NFD labels)

Outputs:

Policy Algorithms

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

This page documents the controller policy algorithms implemented in cmd/operator/main.go.

Use this page after:

Classification Input

Policy demand classification is derived from pod scheduling constraints on joulie.io/power-profile:

performance-only: pod can run only on performance (and transitional draining-performance).
eco-only: pod can run only on eco.
general (implicit unconstrained): no explicit power-profile constraint, or both profiles allowed.
unknown: unsupported/ambiguous constraint shape.

For safety, unknown is treated as performance-sensitive in downgrade guards.

Input Telemetry and Actuation Interfaces

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

This page describes runtime IO contracts:

how Joulie reads telemetry inputs,
how Joulie sends control intents.

It is not the /metrics exposition contract. For exported metrics, see Metrics Reference.

Why this abstraction exists

Joulie must run in two worlds with the same control logic:

real hardware clusters,
simulator/KWOK clusters.

So agent/operator logic depends on provider interfaces, not directly on sysfs or simulator HTTP shape.

Telemetry provider model

Telemetry input can come from:

Metrics Reference

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

Joulie exposes Prometheus metrics from multiple components.

This page covers operator + agent metrics. Simulator metrics are documented separately in:

Simulator Metrics

For telemetry/control input interfaces (host/http routing), see:

Input Telemetry and Actuation Interfaces

Endpoints by component

Agent:
- path: /metrics
- default address: :8080
- env override: METRICS_ADDR
Operator:
- path: /metrics
- default address: :8081
- env override: METRICS_ADDR

Agent metrics

Backend and selected cap

joulie_backend_mode{node,mode} (gauge)
- mode: none|rapl|dvfs
- active mode is 1, others 0
joulie_policy_cap_watts{node,policy} (gauge)
- current selected policy cap in watts

RAPL power/energy

joulie_rapl_energy_uj{node,zone} (gauge)
- latest raw RAPL energy counter in microjoules
joulie_rapl_estimated_power_watts{node,zone} (gauge)
- per-zone estimated power from energy deltas
joulie_rapl_package_total_power_watts{node} (gauge)
- sum of package-level estimated power

DVFS controller

joulie_dvfs_observed_power_watts{node} (gauge)
- observed package power used by DVFS controller
joulie_dvfs_ema_power_watts{node} (gauge)
- EMA-smoothed power used for decisions
joulie_dvfs_throttle_pct{node} (gauge)
- current throttle percentage
joulie_dvfs_above_trip_count{node} (gauge)
- consecutive above-threshold samples
joulie_dvfs_below_trip_count{node} (gauge)
- consecutive below-threshold samples
joulie_dvfs_actions_total{node,action} (counter)
- action: throttle_up|throttle_down

CPU frequency observability

joulie_dvfs_cpu_cur_freq_khz{node,cpu} (gauge)
- current CPU/policy frequency in kHz
joulie_dvfs_cpu_max_freq_khz{node,cpu} (gauge)
- enforced max frequency cap in kHz

Reliability

joulie_reconcile_errors_total{node} (counter)
- reconcile-loop errors

Operator metrics

FSM state and profile label

joulie_operator_node_state{node,state} (gauge)
- state: ActivePerformance|DrainingPerformance|ActiveEco
- active state is 1, others 0
joulie_operator_node_profile_label{node,profile} (gauge)
- operator-applied node label view
- profile: performance|draining-performance|eco
- active profile is 1, others 0

Transition accounting

joulie_operator_state_transitions_total{node,from_state,to_state,result} (counter)
- transition events emitted by operator
- result:
  - applied: transition committed
  - deferred: transition blocked/deferred by safeguards

Notes

Metrics are pull-based; values depend on scrape interval.
Highest cardinality is usually per-CPU frequency series.