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

# Retention Policies

> Configure retention windows, run the Prune Simulator, and enforce compliance retention for Ironcore Backup Solution snapshots.

## Overview

A **retention policy** declares which snapshots to keep and which to remove
based on age and recency. Ironcore Backup Solution (IBS) applies the policy
during scheduled prune runs. The standard compliance pattern across the platform
is **7-day daily** + **3-week weekly** at the Primary DC, with **52-week weekly
archival** at the Backup site.

This page covers the retention syntax, policy placement (job vs. datastore),
the Prune Simulator, and how to roll out a new policy safely.

<Note>
  **Prerequisites**

  * Administrator role on the Polystack platform
  * At least one datastore provisioned
  * At least one backup group with existing snapshots (to preview policy impact)
</Note>

***

## Compliance Retention Pattern

The pattern below satisfies the standard infrastructure retention model. Apply
it consistently across all production workloads.

| Layer           | Policy           | Target                | Purpose                                               |
| --------------- | ---------------- | --------------------- | ----------------------------------------------------- |
| Daily           | `keep-daily=7`   | Primary DC datastore  | Recover any day in the past week                      |
| Weekly          | `keep-weekly=3`  | Primary DC datastore  | Recover a stable weekly snapshot for the past 3 weeks |
| Weekly Archival | `keep-weekly=52` | Backup site datastore | Long-term archival and offsite disaster recovery      |

```mermaid theme={null}
graph LR
    A[Workload] -->|Daily backup| B[Primary DC datastore<br/>keep-daily=7]
    A -->|Weekly full backup| C[Primary DC datastore<br/>keep-weekly=3]
    C -->|Sun 04:30 sync| D[Backup site datastore<br/>keep-weekly=52]
    D -.->|Optional tape| E[Tape library]
```

***

## Retention Window Reference

| Window           | Behaviour                                                   |
| ---------------- | ----------------------------------------------------------- |
| `keep-last=N`    | Keep the N most recent snapshots regardless of age          |
| `keep-hourly=N`  | Keep the most recent snapshot for each of the last N hours  |
| `keep-daily=N`   | Keep the most recent snapshot for each of the last N days   |
| `keep-weekly=N`  | Keep the most recent snapshot for each of the last N weeks  |
| `keep-monthly=N` | Keep the most recent snapshot for each of the last N months |
| `keep-yearly=N`  | Keep the most recent snapshot for each of the last N years  |

Windows can be combined. A snapshot kept by **any** matching window is retained.
For example, with `keep-daily=7, keep-weekly=4, keep-monthly=12`:

* The 7 most recent daily snapshots are kept
* Plus the most recent snapshot in each of the last 4 weeks
* Plus the most recent snapshot in each of the last 12 months

A single snapshot may satisfy multiple windows simultaneously — for example,
a Sunday backup may count as the day, the week, and the month.

***

## Policy Placement

A retention policy can be attached at three levels:

| Level          | Scope                                   | When to Use                                  |
| -------------- | --------------------------------------- | -------------------------------------------- |
| **Backup job** | All snapshots created by that job       | Most common — keeps policy with the workload |
| **Datastore**  | Default for all groups in the datastore | Platform-wide minimums                       |
| **Namespace**  | All groups in that namespace            | Per-team or per-environment overrides        |

Policies cascade with **most-specific wins**: job-level overrides namespace,
which overrides datastore.

<Tip>
  Configure a conservative platform-wide retention at the datastore level
  (for example, `keep-last=2`) as a safety net. Then let individual jobs
  declare their own retention.
</Tip>

***

## Configure a Job Retention Policy

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    <Steps titleSize="h3">
      <Step title="Open the job" icon="external-link">
        Navigate to **Backup Solution** > **Jobs** and open the job.
      </Step>

      <Step title="Open Retention" icon="calendar-days">
        Scroll to the **Retention** section.
      </Step>

      <Step title="Define windows" icon="settings">
        Enter the retention windows — for example:

        * `keep-daily` = 7
        * `keep-weekly` = 3
      </Step>

      <Step title="Preview the impact" icon="search">
        Click **Prune Simulator**. The Simulator lists which existing snapshots
        would be removed and which retained, without making any changes.
      </Step>

      <Step title="Save" icon="check">
        Click **Save**.

        <Check>The new policy is applied on the next prune run for this job's group.</Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash title="Set retention on a job" theme={null}
    ironcore-backup job update \
      --name daily-prod-incr \
      --retention "keep-daily=7,keep-weekly=3"
    ```

    ```bash title="Preview prune impact" theme={null}
    ironcore-backup prune simulate \
      --repository ibs-primary \
      --namespace production \
      --backup-id vm/12345 \
      --retention "keep-daily=7,keep-weekly=3"
    ```
  </Tab>
</Tabs>

***

## Configure a Datastore-Level Policy

A datastore-level policy is the default for any group that does not declare
its own retention.

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    Open the datastore detail page. The **Default Retention** field accepts the
    same windows as job-level retention. Save to apply.
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash theme={null}
    ironcore-backup datastore update \
      --name ibs-primary \
      --default-retention "keep-last=14,keep-weekly=4"
    ```
  </Tab>
</Tabs>

***

## Prune Simulator

The Prune Simulator computes the effect of a retention policy without modifying
any data. Use it before any policy change to confirm the result matches your
intent.

```bash title="Simulate a policy change" theme={null}
ironcore-backup prune simulate \
  --repository ibs-primary \
  --namespace production \
  --backup-id vm/12345 \
  --retention "keep-daily=7,keep-weekly=3,keep-monthly=12"
```

Output:

```
Group: vm/12345
Snapshots: 92
Kept: 22
Removed: 70

Kept snapshots:
  2026-05-21T02:00:00Z   keep-daily   keep-weekly   keep-monthly
  2026-05-20T02:00:00Z   keep-daily
  2026-05-19T02:00:00Z   keep-daily
  ...
```

<Warning>
  Always run the Prune Simulator before applying a more aggressive policy.
  Reducing a retention window does not undo the deletion that follows — only
  the manifests are removed, but chunk garbage collection makes the data
  unrecoverable shortly after.
</Warning>

***

## Prune Schedule

Prune jobs run on the datastore schedule (default: daily 05:00). Adjust as
needed:

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    Open the datastore. Set **Prune Schedule** under **Scheduled Tasks**.
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash theme={null}
    ironcore-backup datastore update \
      --name ibs-primary \
      --prune-schedule "daily 05:00"
    ```
  </Tab>
</Tabs>

After a prune removes a snapshot manifest, the underlying chunks are not
immediately reclaimed. The Garbage Collector reclaims them on the GC schedule
(default: weekly) — see [Datastores](/services/ironcore-backup/admin-guide/datastores).

***

## Compliance Hold

To prevent specific snapshots from being pruned regardless of retention policy,
apply a **Compliance Hold**. Held snapshots are excluded from prune runs until
the hold is removed.

<Tabs>
  <Tab title="Deployment Console" icon="gauge">
    Open the snapshot. Click **Apply Hold**. Enter a reason and the responsible
    user / case number.
  </Tab>

  <Tab title="CLI" icon="terminal">
    ```bash theme={null}
    ironcore-backup snapshot hold add \
      --snapshot ibs-primary:vm/12345/2026-05-21T00:00:00Z \
      --reason "Audit 2026-Q2" \
      --owner audit@polystack
    ```
  </Tab>
</Tabs>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Prune did not remove expected snapshots" icon="alert-triangle">
    Confirm the active policy and check whether a more permissive policy is
    cascading from the namespace or datastore level. Run the Prune Simulator
    to identify the effective policy.
  </Accordion>

  <Accordion title="Snapshots remain in the datastore long after prune" icon="hard-drive">
    Prune only removes the snapshot manifest. The underlying chunks are
    reclaimed at the next Garbage Collection run. Check the GC schedule and
    last GC task result.
  </Accordion>

  <Accordion title="Policy change reduced retention too aggressively" icon="trash-2">
    A more aggressive retention is **permanent once GC runs**. If GC has not
    yet run, restoring the policy and re-running prune may bring back some
    snapshots. Otherwise, restore from the Backup site replica.
  </Accordion>

  <Accordion title="Compliance hold not being honored" icon="lock">
    Confirm the hold is active and not yet expired. Holds are also listed in
    the snapshot detail panel and in the audit log.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Datastores" icon="database" href="/services/ironcore-backup/admin-guide/datastores" color="#bf9667">
    Datastore provisioning and scheduled tasks
  </Card>

  <Card title="Replication and Sync" icon="arrow-left-right" href="/services/ironcore-backup/admin-guide/replication-sync" color="#bf9667">
    Replicate the weekly archival window to the Backup site
  </Card>

  <Card title="Verification and Validation" icon="check" href="/services/ironcore-backup/admin-guide/verification-validation" color="#bf9667">
    Verify retained snapshots and run bi-annual mock drills
  </Card>

  <Card title="Backup Jobs" icon="calendar" href="/services/ironcore-backup/user-guide/backup-jobs" color="#bf9667">
    Operator view of backup jobs and retention
  </Card>
</CardGroup>