`bm ilm rule add`

Syntax

The bm ilm rule add command adds an object lifecycle management rule to a bucket.

The command supports adding both Transition (Tiering) and Expiration lifecycle management rules.

EXAMPLE

The following command adds new lifecycle management rules to the mydata bucket on the mybuckit deployment:

bm ilm rule add --expire-days 90 --noncurrent-expire-days 30  mybuckit/mydata

bm ilm rule add --expire-delete-marker mybuckit/mydata

bm ilm rule add --transition-days 30 --transition-tier "COLDTIER" mybuckit/mydata

bm ilm rule add --noncurrent-transition-days 7 --noncurrent-transition-tier "COLDTIER"

The configured rules have the following effect:

Delete objects more than 90 days old
Delete objects 30 days after they become non-current
Delete DeleteMarker tombstones if that object has no other versions remaining.
Transition objects more than 30 days old to the COLDTIER remote tier.
Transition objects 7 days after they become non-current to the COLDTIER remote tier.

SYNTAX

The command has the following syntax:

bm [GLOBALFLAGS] ilm rule add                               \
                 [--prefix string]                          \
                 [--tags string]                            \
                 [--expire-days "integer"]                  \
                 [--expire-all-object-versions]             \
                 [--expire-delete-marker]                   \
                 [--transition-days "string"]               \
                 [--transition-tier "string"]               \
                 [--noncurrent-expire-days "integer"]       \
                 [--noncurrent-expire-newer "integer"]      \
                 [--noncurrent-transition-days "integer"]   \
                 [--noncurrent-transition-tier "string"]    \
                 [--site-gt "string"]                       \
                 [--size-lt "string"]                       \
                 ALIAS

Brackets [] indicate optional parameters.
Parameters sharing a line are mutually dependent.
Parameters separated using the pipe | operator are mutually exclusive.

Copy the example to a text editor and modify as-needed before running the command in the terminal/shell.

Parameters

ALIAS

Required

The alias and bucket on the Buckit deployment to which to add the object lifecycle management rule.

For example:

bm ilm rule add mybuckit/mydata

--prefix

Optional

Restrict the management rule to a specific object prefix.

For example:

bm ilm rule add --prefix "meetingnotes/" mybuckit/mydata --expire-days "90"

The command creates a rule that expires objects in the mydata bucket of the mybuckit ALIAS after 90 days for any object with the meetingnotes/ prefix.

--tags

Optional

One or more ampersand &-delimited key-value pairs describing the object tags to use for filtering objects to which the lifecycle configuration rule applies.

This option is mutually exclusive with the following option:

--expire-delete-marker

--expire-all-object-versions: Optional

--expire-days

Optional

The number of days to retain an object after being created. Buckit marks the object for deletion after the specified number of days pass. Specify the number of days as an integer, for example 30 for 30 days.

For versioned buckets, the expiry rule applies only to the current object version. Use either the --noncurrent-expire-days flag or the --expire-all-object-versions flag to apply expiration behavior to noncurrent object versions.

Buckit uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

Mutually exclusive with the following options:

--expire-delete-marker

For more complete documentation on object expiration, see Object Expiration and Object Deletion.

--expire-delete-marker

Optional

Specify this option to direct Buckit to remove delete markers for objects with no remaining object versions. Specifically, the delete marker is the only remaining “version” of the given object.

This option is mutually exclusive with the following option:

--tags
--expire-days

For more complete documentation on object expiration, see Object Expiration and Object Deletion.

--transition-days

Optional

The number of calendar days from object creation after which Buckit marks an object as eligible for transition. Buckit transitions the object to the configured remote tier specified to the --transition-tier. Specify the number of days as an integer, e.g. 30 for 30 days. If the remote tier is another Buckit deployment, you can set the value to 0 to mark new objects as immediately eligible for transition to the remote tier.

For versioned buckets, the transition rule applies only to the current object version. Use the --noncurrent-transition-days option to apply transition behavior to noncurrent object versions.

Requires specifying --transition-tier.

For more complete documentation on object transition, see Object Transition (“Tiering”).

--transition-tier

Optional

The remote tier to which Buckit transition objects. Specify an existing remote tier created by bm ilm tier add.

Required if specifying --transition-days.

--noncurrent-expire-days

Optional

The number of days to retain an object version after becoming non-current (i.e. a different version of that object is now the HEAD). Buckit marks noncurrent object versions for deletion after the specified number of days pass.

This option has the same behavior as the S3 NoncurrentVersionExpiration action.

--noncurrent-transition-days

Optional

The number of days an object has been non-current (i.e. replaced by a newer version of that same object) after which Buckit marks the object version as eligible for transition. Buckit transitions the object to the configured remote tier specified to the --transition-tier once the system host datetime passes that calendar date.

This option has no effect on non-versioned buckets. Requires specifying --noncurrent-transition-tier.

This option has the same behavior as the S3 NoncurrentVersionTransition action.

--noncurrent-transition-tier: Optional
The remote tier to which Buckit transitions noncurrent objects versions. Specify a remote tier created by bm ilm tier add.

--noncurrent-expire-newer

Optional

The maximum number of non-current object versions to retain, ordered from newest to oldest.

Use this flag to retain a certain number of past versions of a file in a first in, first out fashion. After retaining the maximum number of non-current versions, Buckit marks any remaining older non-current object versions as eligible for expiration.

The following table lists a number of object versions and their expiration eligibility based on --noncurrent-expire-newer 3:

v5 (current version)	Current version not affected by ILM rules.
v4	retained
v3	retained
v2	retained
v1	marked for expiry

Buckit retains the current version, v5. Buckit also retains the next 3 non-current versions, starting with the newest. This means Buckit marks v4, v3, and v2 for the three non-current version to retain.

v1 would be a fourth non-current version, which falls outside the limit of non-current versions to retain, so Buckit marks v1 for expiration.

Updating the number for this flag only impacts the unmarked versions of objects. Any versions already marked for expiration do not change if you increase the number to retain.

--size-gt: Optional

--size-lt: Optional

Global Flags

This command supports any of the global flags.

Examples

Expire All Bucket Contents After Number of Days

Use bm ilm rule add with the --expire-all-object-versions and --expire-days flags to mark all current and non-current bucket contents for expiration after a number of days pass from the object’s creation:

bm ilm rule add ALIAS/PATH --expire-all-object-versions --expire-days "DAYS"

Replace ALIAS with the alias of the S3-compatible host.
Replace PATH with the path to the bucket on the S3-compatible host.
Replace DAYS with the number of days after which to expire each object. For example, specify 30 to expire objects 30 days after creation.

Transition Non-Current Object Versions at a Prefix to a Different Tier

Use the bm ilm rule add with --prefix and --transition-tier to transition older non-current versions of an object to a different storage tier.

bm ilm rule add --prefix "doc/" --transition-days "90" --transition-tier "MINIOTIER-1"  \
       --noncurrent-transition-days "45" --noncurrent-transition-tier "MINIOTIER-2"    \
       mybuckit/mybucket

This command looks at the contents with the doc/ prefix in the mybucket bucket on the mybuckit deployment.

Current objects in the prefix older than 90 days move to the MINIOTIER-1 storage tier.
Non-current objects in the prefix older than 45 days move to the MINIOTIER-2 storage tier.
Both MINIOTIER-1 and MINIOTIER-2 have already been created with bm ilm tier add.

Expire All Objects at a Prefix, Retain Current Object Versions Longer Than Non-Current Object Versions

Use the bm ilm rule add command with --prefix, --expire-days, and --noncurrent-expire-days to expire current and non-current versions of an object at different times.

bm ilm rule add --prefix "doc/" --expire-days "300" --noncurrent-expire-days "100" mybuckit/mybucket

This command looks at the contents with the doc/ prefix in the mybucket bucket on the mybuckit deployment.

Current objects expire after 300 days.
Non-current objects expire after 100 days.

Transition noncurrent versions in the prefix `/doc` with a size greater the 1MiB

Use the bm ilm rule add command with --prefix, --size-gt, and --noncurrent-expire-days to expire current and non-current versions of an object at different times.

bm ilm rule add --prefix "doc/" --size-gt 1MiB --transition-days "90" --transition-tier "MINIOTIER-1" \
      --noncurrent-transition-days "45" --noncurrent-transition-tier "MINIOTIER-1" \
      mybuckit/mybucket/

This command looks at the contents with the doc/ prefix in the mybucket bucket on the mybuckit deployment.

The command selects the following objects:

Current objects older than 90 days larger than 1MiB.
Non-current objects older than 45 days larger than 1MiB.

Selected objects transition to MINIOTIER-1.

Remove Delete Markers

The following command removes delete markers for objects where the delete marker is the only version of the object that remains.

bm ilm rule add ALIAS/PATH --expire-delete-marker

Replace ALIAS with the alias of the S3-compatible host.
Replace PATH with the path to the bucket on the S3-compatible host.

Note

To delete all versions of an object with a delete marker as its latest version, including the delete marker, consider using batch expiration.

Required Permissions

For permissions required to add a rule, refer to the required permissions on the parent command.

Behavior

Lifecycle Management Object Scanner

Expiry vs Transition

Buckit supports specifying both expiry and transition rules in the same bucket or bucket prefix. Buckit can execute an expiration rule on an object regardless of its transition status. Use bm ilm rule ls to review the currently configured object lifecycle management rules for any potential interactions between expiry and transition rules.

S3 Compatibility

The bm commandline tool is built for compatibility with the AWS S3 API and is tested with Buckit and AWS S3 for expected functionality and behavior.

Buckit provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported. While bm commands may work as documented, any such usage is at your own risk.