Rollback Policies

Rollback policies enable health monitoring and automatic rollback after failed resizes. Use them when you want the controller to monitor workloads after a resize is applied and automatically restore the last known good state if health checks fail. Important: Without a matching rollback policy, the controller will not monitor, rollback, or retry failed resizes. The rollback mechanism is disabled by default until you create a policy.

Scope Mapping

RollbackPolicy is namespaced and applies to workloads within a single namespace.
ClusterRollbackPolicy is cluster-scoped and can apply across multiple namespaces using namespace selectors.

Field Reference

`RollbackPolicy.spec`

Field	Default	Description
`spec.scope`	none	Optional scope object for workload selection within the namespace.
`spec.scope.labelSelector`	none	Kubernetes label selector for matching workloads.
`spec.scope.workloadTypes`	`[Deployment, StatefulSet, CronJob, Rollout, Job, AnalysisRun, DaemonSet, Model]`	Workload kinds this policy applies to. Default excludes `StrimziPodSet` only.
`spec.monitoringPeriod`	none (required)	How long the controller observes an active resize attempt, including newly created pods, before declaring success or starting a rollback. Example: `5m`, `10m`.
`spec.rollbackTarget`	none (required)	Whether rollback returns to `manifest` resources or `lastSuccessful` state.
`spec.adoptionThresholdPercent`	none (required)	Percentage of the workload cohort that must adopt the target resources successfully (1-100).
`spec.backoff.timePeriod`	none (required)	Base duration for a rollback turn. Example: `1m`, `5m`.
`spec.backoff.multiplyByTurn`	none (required)	Scales the base duration by the current turn number. Example: with `timePeriod: 1m` and `multiplyByTurn: 2`, turn 1 waits 2m and turn 2 waits 4m.
`spec.backoff.maxAttempts`	none (required)	Maximum number of turns before the controller marks the rollback as permanently failed.
`spec.weight`	`0`	Higher weight wins when multiple rollback policies match. When weights are equal, older policies win.
`spec.enableMonitoringReopen`	`true`	Set to `false` to stop reopening a completed (`monitoringSucceeded`) turn when a newer replacement pod appears carrying the same recommendation and resources. When disabled, only a genuinely new recommendation starts a fresh monitoring turn for an owner that has already succeeded.

`ClusterRollbackPolicy.spec`

Field	Default	Description
`spec.scope.labelSelector`	none	Kubernetes label selector for matching workloads.
`spec.scope.workloadTypes`	`[Deployment, StatefulSet, CronJob, Rollout, Job, AnalysisRun, DaemonSet, Model]`	Workload kinds this policy applies to. Default excludes `StrimziPodSet` only.
`spec.scope.namespaceSelector.operator`	none	Namespace selector operator: `In` or `NotIn`.
`spec.scope.namespaceSelector.values`	none	Namespace patterns to include or exclude (supports `` wildcards, e.g. `"prod-"`). Wildcard patterns must be enclosed in double quotes.
`spec.monitoringPeriod`	none (required)	How long the controller observes an active resize attempt, including newly created pods, before declaring success or starting a rollback. Example: `5m`, `10m`.
`spec.rollbackTarget`	none (required)	Whether rollback returns to `manifest` resources or `lastSuccessful` state.
`spec.adoptionThresholdPercent`	none (required)	Percentage of the workload cohort that must adopt the target resources successfully (1-100).
`spec.backoff.timePeriod`	none (required)	Base duration for a rollback turn. Example: `1m`, `5m`.
`spec.backoff.multiplyByTurn`	none (required)	Scales the base duration by the current turn number. Example: with `timePeriod: 1m` and `multiplyByTurn: 2`, turn 1 waits 2m and turn 2 waits 4m.
`spec.backoff.maxAttempts`	none (required)	Maximum number of turns before the controller marks the rollback as permanently failed.
`spec.weight`	`0`	Higher weight wins when multiple rollback policies match. When weights are equal, older policies win.
`spec.enableMonitoringReopen`	`true`	Set to `false` to stop reopening a completed (`monitoringSucceeded`) turn when a newer replacement pod appears carrying the same recommendation and resources. When disabled, only a genuinely new recommendation starts a fresh monitoring turn for an owner that has already succeeded.

Example: Namespaced Rollback Policy

apiVersion: rightsizing.kubex.ai/v1alpha1
kind: RollbackPolicy
metadata:
  name: production-rollback
  namespace: production
spec:
  scope:
    labelSelector:
      matchLabels:
        app.kubernetes.io/part-of: storefront
      matchExpressions:
        - key: tier
          operator: In
          values:
            - api
            - worker
    workloadTypes:
      - Deployment
      - StatefulSet
  monitoringPeriod: 5m
  rollbackTarget: lastSuccessful
  adoptionThresholdPercent: 80
  backoff:
    timePeriod: 1m
    multiplyByTurn: 2
    maxAttempts: 3
  weight: 100

Example: Cluster Rollback Policy

apiVersion: rightsizing.kubex.ai/v1alpha1
kind: ClusterRollbackPolicy
metadata:
  name: production-cluster-rollback
spec:
  scope:
    namespaceSelector:
      operator: In
      values:
        - "prod-*"
        - "staging"
    labelSelector:
      matchLabels:
        rollback-enabled: "true"
    workloadTypes:
      - Deployment
      - StatefulSet
      - CronJob
  monitoringPeriod: 10m
  rollbackTarget: lastSuccessful
  adoptionThresholdPercent: 90
  backoff:
    timePeriod: 2m
    multiplyByTurn: 3
    maxAttempts: 5
  weight: 50

Rollback Target Options

`lastSuccessful`

Restores the last known successful resource settings that the controller recorded when monitoring succeeded. This allows the controller to restore intermediate values that worked, rather than going all the way back to the original manifest. Use when you want to preserve incremental progress from successful resizes.

`manifest`

Restores the original resource settings defined in the workload manifest. This ignores any intermediate successful states and returns directly to the baseline. Use when you want predictable, deterministic rollback behavior that always returns to the manifest values.

Recommendation key changes

Rollback fingerprints include the physical recommendation annotation key. Enabling or disabling GlobalConfiguration.spec.multiPolicyContainerRightsizingEnabled can move an otherwise unchanged recommendation between a fixed key and a hashed policy-owned key. Rollback treats that conversion as a new recommendation and restarts its normal monitoring path. No rollback-state migration occurs.

Adoption Threshold

The adoptionThresholdPercent field determines what percentage of the workload cohort (e.g., all pods in a Deployment) must successfully adopt the active recommendation fingerprint before monitoring is considered successful.

Setting 80 means at least 80% of the baseline workload cohort must be healthy on the targeted resources by the end of the monitoring window
Pods count toward the threshold only after they adopt the active recommendation fingerprint and become healthy
The controller evaluates the threshold at the end of the monitoring window, allowing transient restarts or hiccups to recover before deciding whether the resize succeeds or rollback is needed
Newly created pods are monitored through the same window after admission and scheduling; they are not declared successful or rolled back immediately based on their initial health
Range: 1-100

Backoff Turn Calculation

The backoff wait time is calculated as:

wait_time = timePeriod * multiplyByTurn * current_turn

Example with timePeriod: 1m and multiplyByTurn: 2:

Turn 1: 1m * 2 * 1 = 2m
Turn 2: 1m * 2 * 2 = 4m
Turn 3: 1m * 2 * 3 = 6m

After maxAttempts turns are exhausted, the rollback moves to failedPermanent and the controller stops retrying.

Notes

Use namespaced rollback policies when teams own their own namespaces and want namespace-specific rollback behavior.
Use cluster rollback policies when you want consistent rollback behavior across multiple namespaces or the entire cluster.
Model is included in default workload types. Use spec.scope.workloadTypes: [Model] when you want to restrict scope to KubeAI Model objects only. Rollback policy selection and rollback state live on the Model owner, and health monitoring evaluates model-owned pods.
When multiple rollback policies of the same kind match, higher weight wins, then older objects win on ties.
For behavioral details and operational expectations, see Rollback Backoff.
Rollback policies are independent of automation strategies and proactive/static policies - they work alongside those policies to add health monitoring and automatic rollback capabilities.

Understanding Resize vs. Rollback Behavior

Kubex handles how recommendations are applied differently depending on whether a pod is already running or being newly created. Both paths still go through the rollback policy monitoring period before success or rollback is declared:

Kubex receives a recommendation
         │
         ▼
  Is the pod already running?
         │
    ┌────┴────┐
    ▼         ▼
EXISTING     NEW POD
  POD
    │         │
    ▼         ▼
Check node   Apply during
capacity +   admission
safety       (no node
checks       assigned yet)
    │         │
    ├─────────┤
    ▼         ▼
Capacity    Kubernetes
available   schedules pod
or not         │
    │          │
    ▼          │
Resize,        │
evict, or      │
filter         │
    │          │
    └─────┬────┘
          │
          ▼
    No policy? ─────► Retain
          │
          ▼
    Policy matches
          │
          ▼
    Monitoring period
          │
          ▼
  Evaluate health and
  adoption threshold
          │
     ┌────┴────┐
     ▼         ▼
  Healthy  Unhealthy
     │         │
     ▼         ▼
  Success  Rollback
  (retain) to manifest
           or last successful

Key distinctions:

Existing pods: Node capacity checked before action. Insufficient capacity filters the recommendation—the pod is not deleted. Not a rollback.
New pods: Applied during admission before node assignment, then scheduled by Kubernetes. When a rollback policy matches, the pod goes through the configured monitoring period just like an existing pod; only after that window does the controller declare success or start a rollback based on health and adoption results.
Rollback monitoring requires: A recommendation was successfully applied AND a matching rollback policy exists.

Getting Started

Kubernetes Optimization

Public Cloud Optimization

API Reference

Release Notes

Administration

Scope Mapping

Field Reference

`RollbackPolicy.spec`

`ClusterRollbackPolicy.spec`

Example: Namespaced Rollback Policy

Example: Cluster Rollback Policy

Rollback Target Options

`lastSuccessful`

`manifest`

Recommendation key changes

Adoption Threshold

Backoff Turn Calculation

Notes

Understanding Resize vs. Rollback Behavior

​Scope Mapping

​Field Reference

​RollbackPolicy.spec

​ClusterRollbackPolicy.spec

​Example: Namespaced Rollback Policy

​Example: Cluster Rollback Policy

​Rollback Target Options

​lastSuccessful

​manifest

​Recommendation key changes

​Adoption Threshold

​Backoff Turn Calculation

​Notes

​Understanding Resize vs. Rollback Behavior

Scope Mapping

Field Reference

`RollbackPolicy.spec`

`ClusterRollbackPolicy.spec`

Example: Namespaced Rollback Policy

Example: Cluster Rollback Policy

Rollback Target Options

`lastSuccessful`

`manifest`

Recommendation key changes

Adoption Threshold

Backoff Turn Calculation

Notes

Understanding Resize vs. Rollback Behavior