How-to guide Operate a cluster

Roll back an activation

Review the available Activation history and restore the cluster from an earlier deployment.

Use kix rollback to reapply the manifests from a Superseded Activation. A direct rollback requires that Activation’s build output to remain available in the local Nix store.

List the rollback history

Start with the read-only history view:

kix-examples/

❱ kix rollback how-to-application --list
Rollback: activation history for 'how-to-application'

  ● active   how-to-application-kas7c7ssiwy8 (kas7c7ss...)  ← you are here
    source:   /nix/store/55n2cqgxfhyk4n6a47qrf4a9a8j5ma86-k8s-activation-how-to-application

  Superseded (most recent first):

  [1] how-to-application-gb5d6ry45b5l (gb5d6ry4...)  deployed 2026-09-28T08:01:49.095461532+00:00  [store path missing]
      source:   /nix/store/h0zmd6mrdr9r6464x0cjpwa5iwzxq337-k8s-activation-how-to-application

  Run `kix rollback <cluster>` (or `--yes` for most recent) to switch activations.

The output marks the current Activation and lists Superseded Activations from most recent to oldest. Check the deployment time and the local availability of each target. A target marked store path missing cannot be restored by a direct rollback on this machine.

Use structured output when a script needs the history:

kix-examples/ live capture

❱ kix rollback how-to-application --list --output json

Show outputHide output · 18 lines

{
  "cluster": "how-to-application",
  "current": {
    "built_via": "/nix/store/55n2cqgxfhyk4n6a47qrf4a9a8j5ma86-k8s-activation-how-to-application",
    "identity_hash": "kas7c7ssiwy8fj7v9fxa9hi0k7a2i83d",
    "name": "how-to-application-kas7c7ssiwy8"
  },
  "superseded": [
    {
      "available_locally": false,
      "built_via": "/nix/store/h0zmd6mrdr9r6464x0cjpwa5iwzxq337-k8s-activation-how-to-application",
      "deployed_at": "2026-09-28T08:01:49.095461532+00:00",
      "identity_hash": "gb5d6ry45b5ll664ahagxldh9na9z3y5",
      "name": "how-to-application-gb5d6ry45b5l",
      "previous_activation": null
    }
  ]
}

Preview the rollback

Run a dry run and select a target from the numbered history:

kix-examples/

❱ kix rollback how-to-application --dry-run

Kix compares the active Activation with the selected target and prints the package and resource changes. The dry run stops before applying anything.

Apply the rollback

Run the command again without --dry-run:

kix-examples/

❱ kix rollback how-to-application

Select the Activation, review the plan, and confirm it. Kix applies the target through the normal dependency scheduler and readiness checks.

Resources present only in the current Activation are reported but kept by default. Add --prune when the rollback must also remove them:

kix-examples/

❱ kix rollback how-to-application --prune

Review those removals carefully, especially for stateful resources.

Roll back non-interactively

--yes selects the most recent Superseded Activation and skips confirmation:

kix-examples/

❱ kix rollback how-to-application --yes

Use it only when the automation is intended to restore the immediately previous Activation. The command does not accept an Activation name on the command line.

Delegate to the operator

For an operator-managed cluster, add --operator:

kix-examples/

❱ kix rollback how-to-application --operator

Kix selects the rollback target and updates the Activation for the operator to reconcile.

Rollback history is bounded by Activation retention. If the required target has already been retired, restore it from source and deploy it as a new Activation instead.