How Backup Retention Works

Applicable to both Classic and Federated modes

Portworx Backup schedule policy retention determines how long backup data is kept before it is removed. Retention behavior depends on the schedule policy applied to the backup and the type of backup location where backup data is stored. The backup mechanism used for volume data also affects how retention is enforced.

Retain count and incremental count

For backups on standard backup locations, schedule policies control two key retention parameters:

• Retain count: The maximum number of backup copies to keep concurrently. When the number of backups exceeds this count, Portworx Backup deletes older backups to stay within the limit one by one. For Portworx volume backups, Portworx Backup does not delete a backup in a chain until all dependent backups in that chain are no longer needed.

• Incremental count: The number of incremental backups taken between two full backups. Incremental backups capture only the changes since the last backup, so they typically complete faster and use less storage than full backups. When the incremental count is reached, Portworx Backup takes a new full backup. Incremental count applies to both Portworx volumes and generic volumes.

A backup chain is a full backup together with the incremental backups taken after it that depend on it. Because each incremental stores only the changes since the previous backup, every incremental depends on the full backup and on the incrementals before it in the same chain. A new chain starts each time Portworx Backup takes a new full backup (for example, when the incremental count is reached). Portworx Backup does not delete a full or incremental backup until every later backup that depends on it in the chain is also eligible for deletion — otherwise the dependent backups would become unrestorable.

A backup is eligible for deletion when Portworx Backup determines that it is no longer needed. This occurs when newer backups have exceeded the schedule policy's retain count and all subsequent backups that depend on it in the backup chain are also no longer needed. Eligibility for deletion means that Portworx Backup has determined the backup can be removed. Physical deletion then follows, except for backups stored in immutable backup locations, where deletion cannot occur until the provider-side retention period expires. Unless otherwise stated, eligible for deletion is used throughout this topic with this meaning.

Incremental count support depends on the volume type and the Portworx Backup version:

Volume type	Incremental count supported from
Portworx volumes	All supported Portworx Backup versions
Generic volumes	Portworx Backup 2.10.0

note

Incremental backups for generic volumes also require a compatible Stork version on the application cluster. For the qualified Stork version for your Portworx Backup release, see the Feature Support Matrix and Compatibility Matrix.

For Object Lock-enabled schedule policies, the Retain and Incremental count fields are replaced by Auto delete after retention period. When enabled, Portworx Backup waits until a backup becomes eligible for deletion based on the provider-side retention period and then attempts to clean up. When Object Lock is enabled, the Incremental count field is disabled in the UI and cannot be configured; Portworx Backup automatically enforces a fixed incremental count of 5 for backups created under the policy. For more information, see Create schedule policies.

note

For retain-count accounting, Portworx Backup counts backups that produced a usable copy. A successful backup (all selected resources and volumes captured) and a partially successful backup (some, but not all, of the selected resources or volumes captured) both produce a restorable copy and therefore both count toward the retain count. A failed backup captures no usable data, so it is not a retained copy and does not count toward the retain count.

Partially successful backups count against the retain count but may not be eligible for automatic deletion if they contain dependencies or are stored on immutable backup locations. As a result, they can remain longer than expected. To reclaim the space, delete them manually from the web console, CLI, or API. For steps, see Delete Backups.

Retention by backup location type

Main retention rule: Backup-location retention applies only to a protected copy that is actually stored in the backup location. If a backup mechanism keeps the protected copy only as a local snapshot that is never offloaded to a backup location, backup-location retention does not control that snapshot. Which backup mechanisms store a copy in the backup location — and which keep it only locally — is covered in Retention by backup mechanism.

For the copies that are stored in the backup location, how Portworx Backup enforces retention depends on whether the backup location is standard or immutable.

Standard backup locations

On standard backup locations, Portworx Backup manages retention directly using the retain count and schedule policy. Portworx Backup deletes older backups as new ones are created, keeping only the number of backups defined by the retain count.

The following backup location types are standard (non-immutable) by default:

• S3 or S3-compatible object stores without Object Lock enabled
• Azure Blob Storage containers without immutability enabled
• Google Cloud Storage (GCS) buckets without a bucket retention policy
• NFS shares

Immutable backup locations

On immutable backup locations, the storage provider prevents objects from being deleted or overwritten until the configured provider-side retention period expires. Portworx Backup determines when a backup is eligible for deletion, but the storage provider decides whether the deletion is allowed. Backups on immutable locations cannot be physically deleted until the provider-side retention period has expired, regardless of the retain count defined in the schedule policy.

Portworx Backup uses auto-delete-after-retention behavior for immutable backup locations. When a backup becomes eligible for deletion, Portworx Backup attempts to delete it. If the provider-side retention period has not yet expired, the storage provider rejects the delete, so the backup remains in the location and stays marked for deletion. Portworx Backup does not schedule a one-time future deletion; instead, it re-attempts the delete on each subsequent cleanup cycle. A cleanup cycle is the retention-enforcement pass that runs each time a schedule policy executes: Portworx Backup re-evaluates which backups are eligible for deletion under the retain count and retries any deletes that are still pending. The delete succeeds on the first cleanup cycle that runs after the provider-side retention period has expired. Until then, the rejected delete is expected and is not an error condition, and no manual action is required.

warning

If the retain count in the schedule policy is lower than the provider-side retention period, more backups may be stored than the retain count suggests, because backups cannot be physically deleted until provider-side retention expires. Storage usage may also increase as noncurrent object versions accumulate.

Plan capacity around the provider-side retention period, not the retain count alone. As a rough estimate, the peak number of backups retained on an immutable location is the number of backups created during one provider-side retention period:

peak retained backups ≈ backup frequency × provider-side retention period

For example, one backup per day with a 30-day provider-side retention period can retain up to about 30 copies at peak, regardless of a lower retain count, because none can be deleted until they age out of retention. Multiply the peak backup count by your average backup size (allowing for noncurrent versions) to size storage. For a worked example, see Example: estimating stored copies and footprint.

Align schedule interval and retention periods

On immutable backup locations, configure the schedule and retention values consistently to avoid repeated failed deletes or rejected writes:

• Keep the schedule interval shorter than the schedule policy's retention period, so each backup is retained for its full intended window before it becomes eligible for deletion.
• Keep the schedule policy's retention period greater than or equal to the provider-side (bucket or container) retention period. If the policy retention is shorter, Portworx Backup marks backups for deletion while the provider still blocks them, producing repeated (expected) failed delete attempts until the provider-side period expires. On object lock-enabled buckets, misaligned settings can also cause rejected writes.

S3 or S3-compatible backup locations with Object Lock

When Object Lock is enabled on an S3 bucket:

• Portworx Backup decides when a backup is eligible for deletion, but the S3 provider enforces provider-side retention.
• Deletes are blocked until the provider-side retention period configured on the bucket expires.
• The retention mode determines whether early deletion is possible before the retention period expires:
  • Compliance mode: No one, including the AWS account root user, can delete or overwrite a locked object version until its retention period expires.
  • Governance mode: A user granted the s3:BypassGovernanceRetention permission (with the x-amz-bypass-governance-retention:true header) can delete a locked object before its retention period expires. Governance mode protects against accidental deletion while still allowing an authorized administrator to remove objects early. Portworx Backup does not bypass Governance-mode retention on its own; its automatic retention behavior treats both modes the same and waits for the retention period to expire. Early deletion in Governance mode is a manual, out-of-band action performed directly against S3 by an authorized user.
• The bucket must be created with Object Lock enabled, versioning enabled, a default retention mode (Compliance or Governance), and a configured retention period. Object Lock cannot be enabled on an existing bucket.
• S3 Lifecycle Management (LCM) rules are still required to clean up noncurrent object versions and delete markers. Without lifecycle rules, noncurrent versions and delete markers accumulate indefinitely even after Portworx Backup removes the backup entry.

For configuration steps, see Add an Object Lock-Enabled S3 Backup Location.

Azure immutable backup locations

When Azure Blob immutability is enabled:

• Portworx Backup waits for a backup to become eligible for deletion, but Azure enforces the retention period.
• Deletes are blocked until the Azure retention period expires.
• Azure supports version-level WORM (Write Once Read Many) policies at both the storage account and container levels. Container-level policies take precedence over storage account-level policies.

For configuration steps, see Add an Azure Immutable Backup Location.

GCS immutable backup locations

When a Google Cloud Storage (GCS) bucket has a retention policy configured (optionally locked with Bucket Lock):

• Portworx Backup waits for a backup to become eligible for deletion, but GCS enforces the retention period.
• Deletes are blocked until an object meets the bucket's retention period. Objects cannot be deleted or overwritten before that period elapses.
• If the retention policy is locked using Bucket Lock, it cannot be reduced or removed, and the bucket cannot be deleted until every object meets the retention period. A retention policy applies to all current and future objects in the bucket.
• If object versioning is enabled, configure GCS Object Lifecycle Management rules to remove noncurrent versions after they age out. Without lifecycle rules, noncurrent versions accumulate even after Portworx Backup removes the backup entry.

For details on GCS retention behavior, see Retention policies and Bucket Lock in the Google Cloud documentation.

Retention by backup mechanism

The backup mechanism used for volume data determines whether the protected copy is stored in the backup location and whether backup-location retention applies to it.

Recall the main retention rule: backup-location retention applies only to a protected copy that is stored in the backup location. If the protected copy remains only as a local CSI (Container Storage Interface) snapshot and is never offloaded to a backup location, backup-location retention does not control that snapshot. The mechanisms below differ in whether they place a copy in the backup location.

Portworx cloud snapshots

Portworx Backup creates a Portworx cloud snapshot and stores it in the configured backup location.

• On standard backup locations, retention follows the retain count. A backup is not deleted until all dependent backups in the chain are no longer needed.
• On immutable backup locations, the backup objects stored in the target location are protected by provider-side retention.

Native CSI snapshots without offload

Portworx Backup uses the storage provider's CSI driver to create a local snapshot on the storage platform. The snapshot remains local to the storage system or cloud disk and is not uploaded to the backup location.

• Backup-location retention applies only to the resource metadata files uploaded to the backup location, not to the snapshot data itself.
• The local CSI snapshots are still cleaned up — they follow the schedule policy retain count. When a backup ages out of the retain count and is deleted, Portworx Backup removes the associated local CSI snapshot (the VolumeSnapshot) on the application cluster along with the backup's metadata in the backup location. The retain count therefore governs local snapshot cleanup, even though the snapshot data never resides in the backup location. Native CSI snapshots are not left uncleaned.
• Immutable settings on the backup location do not protect a native CSI snapshot that was never offloaded there.

CSI snapshots with KDMP offload

The CSI driver creates a local snapshot, and KDMP copies the snapshot contents to the configured backup location. Each backup chain creates a new Kopia repository in the backup location.

• The local snapshot remains on the storage platform, and the offloaded copy is stored in the backup location.
• Backup-location retention applies to the offloaded copy in the object store or NFS location.
• The local snapshot and the offloaded copy belong to the same backup and follow the same schedule policy retain count. When the backup ages out of the retain count and is deleted, Portworx Backup removes both the offloaded copy in the backup location and the local CSI snapshot on the storage platform. Provider-side immutability protects only the offloaded copy in the backup location; it does not extend to the local snapshot.
• On immutable backup locations, provider-side retention protects the offloaded copy in the target bucket or NFS location after Portworx Backup writes the data there.

note

CSI snapshots with KDMP offload are available in Classic mode only. NFS backup locations are not supported in Federated mode.

Direct KDMP backups

The KDMP driver copies file-system data from the volume directly to the backup location without creating a local CSI snapshot. Each backup chain creates a new Kopia repository in the backup location.

• Backup-location retention applies directly to the stored backup data in the backup location.
• On immutable backup locations, provider-side retention protects the copied data in the target bucket, NFS share, or object-store location.

note

Direct KDMP backups are available in Classic mode only.

How retention applies to Kopia repositories

For both CSI snapshots with KDMP offload and Direct KDMP backups, each backup chain is stored as its own Kopia repository in the backup location; retention does not prune blocks across a single shared repository. When an individual backup in a chain becomes eligible for deletion, Portworx Backup prunes that backup's data (its snapshots and the blocks that no other backup references) from that chain's Kopia repository. When every backup in a chain has aged out and been deleted, the entire per-chain Kopia repository is removed. On immutable backup locations, this pruning and removal still cannot physically occur until the provider-side retention period expires.

Classic mode and Federated mode behavior

Retention behavior differs between operation modes in how physical deletion is performed.

In Classic mode, Portworx Backup performs physical deletion directly as part of the delete workflow. The Portworx Backup server manages backup deletion for all supported backup location types.

In Federated mode, physical cleanup is performed by Stork on the application cluster. The Portworx Backup server instructs Stork to delete the backup, and Stork performs the deletion using Workload Identity — a secret-less mechanism that lets Stork authenticate directly to the backup location without credentials stored on the Portworx Backup server. For more information, see Federated Mode Specifications.

Federated mode also imposes the following backup location and backup mechanism limitations:

• The supported backup locations are Azure Blob Storage, AWS S3, and Google Cloud Storage (GCS).
• NFS backup locations are not supported.
• KDMP-based backup types (Direct KDMP and CSI local snapshot with KDMP offload) are not available.

Because these types are unavailable in Federated mode, the retention behavior described in Retention by backup mechanism applies to Classic mode only.

For more information on mode differences, see Operation Modes.

Manual (on-demand) backups

Retain count and incremental count are schedule policy settings, so they apply only to scheduled backups. Manual (on-demand) backups are not governed by a schedule policy and are never automatically deleted by retention — they persist until you delete them explicitly from the web console, CLI, or API.

• On standard backup locations, a manual backup is removed as soon as you delete it (subject to backup-chain dependencies).
• On immutable backup locations, deleting a manual backup removes the Portworx Backup entry, but the backup data cannot be physically removed until the provider-side retention period expires.
• Like scheduled backups, a manual backup that is part of a backup chain is not physically removed until every later backup that depends on it is also deleted.

For deletion steps, see Delete Backups.

Important considerations

Deleting a schedule does not delete existing backups

Deleting a backup schedule or schedule policy removes the policy configuration but does not delete backups that have already been created under that schedule. You must delete those backups separately.

Pausing a schedule also pauses its retention cleanup

Retention is enforced during the cleanup cycle that runs each time a schedule executes. Pausing (suspending) a backup schedule stops new backups from being created and also pauses retention enforcement for that schedule — existing backups are not re-evaluated for deletion while the schedule is paused. On immutable backup locations, a backup that became eligible for deletion but was rejected by provider-side retention is not retried until you resume the schedule. Resuming the schedule resumes normal retention enforcement, and the pending deletions are retried on the next cleanup cycle. If you need to remove such backups while the schedule is paused, delete them manually from the web console, CLI, or API.

Changing retain count or incremental count

• Retain count: A change takes effect on the next retention cycle and is evaluated against the existing backups. Lowering the retain count marks the now-excess older backups as eligible for deletion (subject to backup-chain dependencies, and to provider-side retention on immutable locations). Raising it keeps more backups going forward.
• Incremental count: A change applies only to future backup chains. Chains that already exist keep the structure they had when they were created; the new value takes effect from the next full backup.

Metrics retention is not backup-data retention

Portworx Backup metrics retention (how long monitoring metrics are stored) is separate from backup-data retention. Backup-data retention controls how long Portworx Backup keeps your backup copies. Configuring metrics retention does not affect how long Portworx Backup stores your backup data. To configure how long metrics are retained, see Configure Observability — for example, the prometheus.storage and retentionSize settings in Configure Portworx Backup Prometheus, or the Prometheus retention settings in Configure your Own Prometheus.

Example: estimating stored copies and footprint

The number of copies Portworx Backup keeps, and the resulting storage footprint, depend on the retain count, the incremental count, and any provider-side retention on immutable locations. The following example illustrates how these combine.

Assume a daily schedule policy on a standard backup location with:

• Retain count = 7 (keep the 7 most recent backups)
• Incremental count = 6 (6 incremental backups between two full backups)

With these values, each cycle produces 1 full backup followed by 6 incrementals (7 backups per chain). At steady state, Portworx Backup keeps about 7 backups: roughly 1 full backup plus its incrementals. Because incrementals capture only changes since the previous backup, the footprint is approximately one full-backup size plus the accumulated daily change over the retained window, not seven full copies. On Portworx volume backups, a backup in a chain is not deleted until all dependent backups in that chain are no longer needed, so a chain may briefly hold more than the retain count until its dependencies clear.

On an immutable backup location, the estimate changes. If the provider-side retention period is longer than the time it takes to accumulate the retain count of backups, copies persist until provider-side retention expires even though Portworx Backup marked them for deletion. In that case, plan capacity around the provider-side retention period rather than the retain count.

note

These numbers are illustrative. Actual footprint depends on data change rate, backup mechanism (full cloud snapshot versus KDMP incremental), and provider-side retention settings.

Troubleshooting

Symptom	Likely cause and action
Backups accumulate beyond the retain count on an immutable backup location	Backups cannot be physically deleted until provider-side retention expires. Verify the configured retention period and any lifecycle policies on the bucket or container, and plan storage capacity based on the retention period rather than the configured retain count.
Noncurrent object versions or delete markers accumulate on an Object Lock S3 bucket	Portworx Backup removes the backup entry, but the provider retains noncurrent versions. Confirm that S3 Lifecycle Management (LCM) rules are configured to clean up noncurrent versions and delete markers.
Delete attempt fails on an immutable backup location	Expected before the provider-side retention period expires. No action is required; Portworx Backup retries deletion after retention expires.
Partially successful backups remain beyond the retain count	They count against the retain count but may not be auto-deleted if they have dependencies or are on immutable locations. Delete them manually from the web console, CLI, or API. See Delete Backups.

Related topics

• Schedule Policies
• Create Schedule Policies
• Backup Types by Driver
• Add an Object Lock-Enabled S3 Backup Location
• Add an Azure Immutable Backup Location