mizcausevic-dev/llm-cost-budget-operator

Purpose and principal workflow: A cluster administrator creates an LLMCostBudget through the Kubernetes API, and the operator evaluates it against spend held in a referenced ConfigMap. A cost pipeline—documented as paired with llm-cost-span-exporter—writes the running total; the operator records budget posture in resource status and emits Warning events for warning or over-budget states.

Components

Declarative budget API

• Budget author — *null repository path*: creates budget resources specifying a monthly USD limit, warning threshold, and ConfigMap/key cost source.

• LLMCostBudget resource contract — api/v1alpha1/llmcostbudget_types.go: defines the spec, status, conditions, and reported budget states used by the operator and Kubernetes API.

• Kubernetes API server — *null repository path*: stores budget resources and ConfigMaps, serves reads and status updates, and exposes events.

Operator runtime

• Manager entry point — cmd/main.go: registers Kubernetes and budget types, creates the controller-runtime manager and event recorder, and registers the reconciler.

• Budget reconciler — internal/controller/llmcostbudget_controller.go: responds to budget and ConfigMap watches, reads source data, handles missing or invalid inputs, updates status, emits events, and schedules hourly requeues.

Evaluation

• Budget evaluator — internal/budget/budget.go: parses limit and observed spend, applies the default 80% warning threshold when unset, computes rounded percent used and state, and formats USD values.

Spend input

• Cost pipeline — *null repository path*: the documented external pipeline computes cost and writes the accumulated total to the ConfigMap referenced by a budget.

Relationships

• Budget author -> Kubernetes API server: creates an LLMCostBudget; the README describes declarative resources applied to the cluster.

• Kubernetes API server -> Manager entry point: supplies cluster configuration used by the manager; cmd/main.go obtains it through ctrl.GetConfigOrDie().

• Manager entry point -> Budget reconciler: registers the reconciler and its budget and ConfigMap watches.

• Budget reconciler -> Kubernetes API server: watches and reads budget resources, and lists budgets in a ConfigMap’s namespace to map changes to reconcile requests.

• Budget reconciler -> Kubernetes API server: reads the referenced ConfigMap and its configured data key during reconciliation.

• Cost pipeline -> Kubernetes API server: writes accumulated spend to a ConfigMap; this is documented behavior, not shown in sampled source.

• Budget reconciler -> Budget evaluator: passes the budget spec and observed spend string to Evaluate.

• Budget evaluator -> Budget reconciler: returns the calculated spend, percent, and state; the reconciler formats results and builds status conditions.

• Budget reconciler -> Kubernetes API server: writes budget status, including spend, percent, state, and conditions.

• Budget reconciler -> Kubernetes API server: records Warning events for warning and over-budget states through its event recorder.

• Kubernetes API server -> Budget reconciler: a changed referenced ConfigMap is mapped to reconcile requests; the reconciler also requeues hourly as a safety net.

Coverage limits: The README documents the CRD, Helm installation, and exporter pairing, but their runtime installation details and the external cost-writing pipeline are not present in the sampled source. The precise event delivery and downstream alert-consumer path are not established.