RolloutAnalysis CRD

RolloutAnalysis is a reusable template of metric measurements. An AgentRuntime rollout step of type analysis names a template; the AgentRuntime controller takes the measurements, and the rollout advances only if every metric passes. A metric reads its value from one of three providers: prometheus, web or arenaEval.

RolloutAnalysis is an Enterprise resource. The CRD ships with the Enterprise chart; without it, an analysis step fails with RolloutAnalysis CRD not installed (EE feature) and requeues (see Installing a License).

API Version

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: RolloutAnalysis

Short name: ra (e.g. kubectl get ra, which lists the metric names and the age).

Resource Scope

RolloutAnalysis is namespaced. A step finds its template in the namespace of the AgentRuntime. The CRD carries the helm.sh/resource-policy=keep annotation, so helm uninstall leaves the resources in place.

How Templates Are Used

An AgentRuntime step references a template by name and can override its arguments:

spec:
  rollout:
    steps:
      - setWeight: 20
      - analysis:
          templateName: error-rate
          args:
            - name: window
              value: 10m

See rollout for the step fields.

Each pass evaluates every metric in the template and takes at most one measurement per metric. A metric whose next measurement falls after the current time is skipped for that pass. The controller persists progress in AgentRuntime.status.rollout.analysis. Progress is discarded when the step, template name, template metadata.generation or candidate version changes, so editing a template spec restarts its measurements.

Outcome	Condition	Controller action
In progress	Some metric still owes measurements.	Records progress and requeues for the nearest due interval (at least 1s). The rollout stays on the step.
Passed	Every metric completed count measurements without exceeding failureLimit.	Advances to the next step.
Failed	A metric’s failed measurements exceed its failureLimit.	With rollout.rollback.mode: automatic, rolls back to stable. With any other rollback mode (including unset), the rollout stays on the step with RolloutActive=True, reason AnalysisFailed. The controller does not requeue on a timer. Measurement progress is cleared, so any later reconcile restarts the measurements from zero, and the status update that records the failure triggers one. The measurements stop restarting only when a fresh run fails on its first pass with the same message, which leaves the status unchanged; after that, an edit to the spec restarts them.
Error	The template is missing or invalid, a provider call fails, or the condition cannot be parsed.	Logs, requeues after 30s, and does not roll back. The failed attempt is not counted as a measurement or a failure.

A metric that has exceeded its failureLimit decides the run as failed even when another metric errors in the same pass.

Each completed run increments omnia_rollout_analysis_runs_total (labels namespace, agentruntime, template, result of pass or fail).

Spec Fields

args

Template arguments with defaults. A step’s analysis.args override a default of the same name.

Field	Type	Required	Description
name	string	yes	Argument name. Minimum length 1.
value	string	no	Default value.

Arguments are substituted by replacing {{args.<name>}} in:

• prometheus.query
• web.url
• the values of web.headers

No other field is substituted.

metrics (required)

One or more metrics. At least one is required. All metrics must pass for the analysis to pass.

Field	Type	Required	Description
name	string	yes	Metric identifier, used in logs, progress and the failure message. Minimum length 1.
interval	string	yes	Go duration between measurements (e.g. 1m, 5m). A value that does not parse, or is negative, is an error.
count	int32	yes	Number of measurements to take. Minimum 1.
failureLimit	int32	no	Failed measurements tolerated. The metric fails once failures exceed this number. Minimum 0, default 0.
successCondition	string	yes	Condition evaluated against the metric value (see below).
provider	object	yes	Where the value comes from: prometheus, web or arenaEval. Nothing validates that only one is set. When several are set, the controller uses the first present in the order prometheus, web, arenaEval.

The first measurement runs on the first pass; each later one runs one interval after the previous.

successCondition

The condition must match result[N] <op> <number>, where <op> is one of >=, <=, >, <, == or !=. Each provider returns one number, so the index N does not select among values. For example, result[0] <= 0.05.

A measurement passes when the condition holds and counts as failed when it does not. A condition in any other form is an error.

provider.prometheus

Runs an instant PromQL query and compares the first result. A vector result uses its first sample; a scalar result is used directly; an empty vector is an error.

Field	Type	Required	Description
address	string	yes	Prometheus server URL, e.g. http://prometheus:9090. Minimum length 1.
query	string	yes	PromQL query. Supports {{args.<name>}}. Minimum length 1.

provider.web

Calls an HTTP endpoint and extracts a number from the response.

Field	Type	Required	Default	Description
url	string	yes	—	Endpoint URL. Supports {{args.<name>}}. Minimum length 1.
method	enum	no	GET	GET or POST.
headers	map[string]string	no	—	Request headers. Values support {{args.<name>}}.
jsonPath	string	no	—	JSONPath expression selecting the value in a JSON response.
timeout	int32	no	30	Request timeout in seconds. A value of 0 or less uses 30.

Without jsonPath, the whole response body must be a bare number. With jsonPath, the expression must select exactly one value, which is a number or a numeric string. The controller reads at most 1 MiB of the response. A non-2xx status is an error, not a failed measurement. The request has no body.

provider.arenaEval

Reads the average score of an evaluation definition for the candidate variant from session-api. The controller resolves the session-api of the AgentRuntime’s namespace and service group (spec.serviceGroup, default default) and authenticates with the operator’s session-api token.

Field	Type	Required	Description
evalDef	string	yes	Evaluation definition ID. Minimum length 1.

The query is fixed to the avg_score aggregate and the variant candidate. The operator sets OMNIA_VARIANT=candidate on candidate pods, so their sessions, and the eval results scored against them, are recorded with variant candidate. Results from stable pods are not counted. When the evaluation has produced no results for the candidate yet, the measurement is an error and is retried, not a failed measurement.

Status

The CRD has a status subresource and no status fields. Measurement progress is recorded on the AgentRuntime, under status.rollout.analysis.

Examples

Error rate from Prometheus

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: RolloutAnalysis
metadata:
  name: error-rate
  namespace: production
spec:
  args:
    - name: window
      value: 5m
  metrics:
    - name: error-rate
      interval: 1m
      count: 5
      failureLimit: 1
      successCondition: "result[0] <= 0.05"
      provider:
        prometheus:
          address: http://prometheus.monitoring:9090
          query: |
            sum(rate(omnia_agent_requests_total{status="error"}[{{args.window}}]))
            / sum(rate(omnia_agent_requests_total[{{args.window}}]))

Web provider and arenaEval together

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: RolloutAnalysis
metadata:
  name: quality-gate
  namespace: production
spec:
  metrics:
    - name: health-score
      interval: 2m
      count: 3
      successCondition: "result[0] >= 0.9"
      provider:
        web:
          url: https://metrics.example.com/api/score
          headers:
            Accept: application/json
          jsonPath: "{.data.score}"
          timeout: 10
    - name: answer-quality
      interval: 5m
      count: 3
      failureLimit: 1
      successCondition: "result[0] >= 0.8"
      provider:
        arenaEval:
          evalDef: answer-quality

Related Resources

• AgentRuntime CRD: spec.rollout.steps[].analysis.
• Rollout strategies: how analysis steps fit into a canary rollout.
• Progressive rollouts: a canary rollout with setWeight and pause steps and automatic rollback. Add an analysis step to gate a step on a RolloutAnalysis.
• Real-time evals: the omnia_eval_* metrics a gate can key on.