> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```yaml theme={null}
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

```yaml theme={null}
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](https://docs.kubex.ai/docs-kubex/Content/Kubex/automation-engine/rollback-backoff.md).
* 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.