Lifecycle rule patterns

This page describes common lifecycle rule patterns for different retention and cleanup scenarios. For general lifecycle management concepts, see Object Lifecycle Management. For the full CLI reference, see mc ilm rule add.

Expire objects after N days (unversioned bucket)

Delete objects older than a specified number of days on a bucket without versioning:

mc ilm rule add ALIAS/BUCKET --expire-days 90

The scanner evaluates each object’s creation date and deletes it once the specified days have passed.

Expire objects after N days (versioned bucket)

On a versioned bucket, expiring the current version creates a delete marker. Use two rules to fully clean up:

Rule 1: expire the current version (creates a delete marker):

mc ilm rule add ALIAS/BUCKET --expire-days 1095

Rule 2: expire noncurrent versions and clean up orphan delete markers:

mc ilm rule add ALIAS/BUCKET --noncurrent-expire-days 1 --expire-delete-marker
Set --noncurrent-expire-days to a value that matches your recovery window. A value of 1 removes noncurrent versions after one day. Use a higher value if you need to retain previous versions for rollback.

Purge all versions of an object

Version requirement

The --purge-all-object-versions-days and --purge-all-object-versions-delete-marker flags require MinIO Server RELEASE.2024-11-07T18-50-04Z or later and AIStor Client RELEASE.2024-11-08T20-15-40Z or later.

For older versions, use the two-rule pattern described in Expire objects after N days (versioned bucket) instead.

Delete all versions (current, noncurrent, and delete markers) of an object after a specified number of days since the latest version was created:

mc ilm rule add ALIAS/BUCKET --purge-all-object-versions-days 1095 --purge-all-object-versions-delete-marker

This is a single rule that handles both live objects and objects with a delete marker as the latest version.

Use this pattern when:

  • You do not need to retain noncurrent versions for any recovery window
  • You want a single rule instead of managing separate expiration and noncurrent rules
  • The bucket has versioning enabled for replication but applications only write one version per object

Clean up orphan delete markers

Remove delete markers that have no remaining noncurrent versions behind them:

mc ilm rule add ALIAS/BUCKET --expire-delete-marker

This is a standalone rule. It removes delete markers immediately when they become the only remaining version of an object.

Abort incomplete multipart uploads

Remove incomplete multipart uploads that have been abandoned by clients. This prevents orphan parts from consuming disk space:

mc ilm rule add ALIAS/BUCKET --expire-days 7
On an unversioned bucket, --expire-days applies to both complete objects and incomplete multipart uploads. Ensure the value is appropriate for both use cases, or use a prefix to scope the rule.

Retain a fixed number of noncurrent versions

Version requirement
The --noncurrent-expire-newer flag requires AIStor Client RELEASE.2024-09-19T07-30-39Z or later.

Keep only the N most recent noncurrent versions and expire older ones:

mc ilm rule add ALIAS/BUCKET --noncurrent-expire-days 30 --noncurrent-expire-newer 3

This retains the 3 most recent noncurrent versions and expires any noncurrent version older than 30 days.

Scope rules by prefix

Apply a lifecycle rule to a specific prefix within a bucket:

mc ilm rule add ALIAS/BUCKET --prefix "logs/" --expire-days 30

This only affects objects under the logs/ prefix. Other objects in the bucket are not evaluated by this rule.

Choosing the right pattern

Scenario Rule
Simple expiration, no versioning --expire-days N
Versioned bucket, keep noncurrent for recovery --expire-days N + --noncurrent-expire-days M --expire-delete-marker
Versioned bucket, delete everything after N days --purge-all-object-versions-days N --purge-all-object-versions-delete-marker
Clean up orphan delete markers --expire-delete-marker
Abort stale multipart uploads --expire-days N (or scope with --prefix)
Keep only recent versions --noncurrent-expire-days N --noncurrent-expire-newer M

Monitoring lifecycle activity

Key metrics

Metric Description
minio_ilm_action_count_delete (v3) Total deletions performed by ILM
minio_ilm_expiry_missed_tasks (v3) Expirations skipped because the scanner could not keep up. Should remain at zero.

Scanner status

Check the scanner’s current progress and throughput:

mc admin scanner status ALIAS

If ILM, DeleteAction throughput is lower than expected, reduce the scanner delay to increase scan speed:

mc admin config set ALIAS scanner delay=5.0

Return to the default after the backlog is cleared:

mc admin config set ALIAS scanner delay=10.0

Lifecycle with site replication

When site replication is configured, lifecycle expiration rules are not replicated automatically across sites. Apply the same rules on each site independently if you want consistent expiration behavior.

ILM expiry rule replication was added in later releases. If you see minio.repl.ilm.pending warnings in SUBNET diagnostics, upgrade to the latest release.