mc ilm rule add
The mc ilm rule add
command adds an object lifecycle management rule to a bucket.
Syntax
The command supports adding both Transition (Tiering) and Expiration lifecycle management rules.
Parameters
ALIAS
Required
The alias and bucket on the AIStor deployment to which to add the object lifecycle management rule.
For example:
mc ilm rule add myminio/mydata
--prefix
Optional
Restrict the management rule to a specific object prefix.
For example:
mc ilm rule add --prefix "meetingnotes/" myminio/mydata --expire-days "90"
The command creates a rule that expires objects in the mydata
bucket of the myminio
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-days
Optional
The number of days to retain an object after being created.
AIStor 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 --purge-all-object-versions-days
flag to apply expiration behavior to noncurrent object versions.
AIStor 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:
For more complete documentation on object expiration, see Object Expiration and Object Deletion.
--expire-delete-marker
Optional
Specify this option to direct AIStor 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:
AIStor 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.
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 AIStor marks an object as eligible for transition.
AIStor 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 AIStor 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
.
AIStor 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.
For more complete documentation on object transition, see Object Transition (“Tiering”).
--transition-tier
Optional
The remote tier to which AIStor transition objects.
Specify an existing remote tier created by mc 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). AIStor marks noncurrent object versions for deletion after the specified number of days pass.
This option has the same behavior as the S3 NoncurrentVersionExpiration
action.
AIStor 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.
--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 AIStor marks the object version as eligible for transition.
AIStor 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.
AIStor 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.
--noncurrent-transition-tier
Optional
The remote tier to which AIStor transitions noncurrent objects versions.
Specify a remote tier created by mc 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, AIStor 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 |
AIStor retains the current version, v5.
AIStor also retains the next 3
non-current versions, starting with the newest.
This means AIStor 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 AIStor 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.
AIStor 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.
--size-gt
Optional
Select objects larger than the specified value.
Enter the value as a number and a unit, such as 5GiB
for 5 gibibytes.
Valid units include:
Suffix | Unit Size |
---|---|
k |
KB (Kilobyte, 1000 Bytes) |
m |
MB (Megabyte, 1000 Kilobytes) |
g |
GB (Gigabyte, 1000 Megabytes) |
t |
TB (Terrabyte, 1000 Gigabytes) |
ki |
KiB (Kibibyte, 1024 Bites) |
mi |
MiB (Mebibyte, 1024 Kibibytes) |
gi |
GiB (Gibibyte, 1024 Mebibytes) |
ti |
TiB (Tebibyte, 1024 Gibibytes) |
--size-lt
Optional
Select objects smaller than the specified value.
Enter the value as a number and a unit, such as 1M
for 1 megabyte.
Valid units include:
Suffix | Unit Size |
---|---|
k |
KB (Kilobyte, 1000 Bytes) |
m |
MB (Megabyte, 1000 Kilobytes) |
g |
GB (Gigabyte, 1000 Megabytes) |
t |
TB (Terrabyte, 1000 Gigabytes) |
ki |
KiB (Kibibyte, 1024 Bites) |
mi |
MiB (Mebibyte, 1024 Kibibytes) |
gi |
GiB (Gibibyte, 1024 Mebibytes) |
ti |
TiB (Tebibyte, 1024 Gibibytes) |
--purge-all-object-versions-days
Optional
Specify the number of days after which to delete all versions of an object. This flag does not remove delete markers.
To remove delete markers, use --expire-delete-marker
or --purge-all-object-versions-delete-marker
.
--purge-all-object-versions-delete-marker
Optional
Use this flag to purge all versions of objects where the latest version of the object is a delete marker, including the delete marker.
Global Flags
This command supports any of the global flags.
Examples
Expire All Bucket Contents After Number of Days
Use mc ilm rule add
with the --purge-all-object-versions-days
flag to mark all current and non-current bucket contents for expiration after a number of days pass from the object’s creation:
mc ilm rule add ALIAS/PATH --purge-all-object-versions-days "DAYS"
- Replace
ALIAS
with thealias
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, specify30
to expire objects 30 days after creation.
Transition Non-Current Object Versions at a Prefix to a Different Tier
Use the mc ilm rule add
with --prefix
and --transition-tier
to transition older non-current versions of an object to a different storage tier.
mc ilm rule add --prefix "doc/" --transition-days "90" --transition-tier "MINIOTIER-1" \
--noncurrent-transition-days "45" --noncurrent-transition-tier "MINIOTIER-2" \
myminio/mybucket
This command looks at the contents with the doc/
prefix in the mybucket
bucket on the myminio
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
andMINIOTIER-2
have already been created withmc ilm tier add
.
Expire All Objects at a Prefix, Retain Current Object Versions Longer Than Non-Current Object Versions
Use the mc 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.
mc ilm rule add --prefix "doc/" --expire-days "300" --noncurrent-expire-days "100" myminio/mybucket
This command looks at the contents with the doc/
prefix in the mybucket
bucket on the myminio
deployment.
- Current objects expire after 300 days.
- Non-current objects expire after 100 days.
/doc
with a size greater the 1MiB
Transition noncurrent versions in the prefix Use the mc 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.
mc ilm rule add --prefix "doc/" --size-gt 1MiB --transition-days "90" --transition-tier "MINIOTIER-1" \
--noncurrent-transition-days "45" --noncurrent-transition-tier "MINIOTIER-1" \
myminio/mybucket/
This command looks at the contents with the doc/
prefix in the mybucket
bucket on the myminio
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.
mc ilm rule add ALIAS/PATH --expire-delete-marker
- Replace
ALIAS
with thealias
of the S3-compatible host. - Replace
PATH
with the path to the bucket on the S3-compatible host.
Required Permissions
For permissions required to add a rule, refer to the required permissions on the parent command.
Behavior
Lifecycle Management Object Scanner
AIStor 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.
Expiry vs Transition
AIStor supports specifying both expiry and transition rules in the same bucket or bucket prefix.
AIStor can execute an expiration rule on an object regardless of its transition status.
Use mc ilm rule ls
to review the currently configured object lifecycle management rules for any potential interactions between expiry and transition rules.
S3 Compatibility
The mc
commandline tool is built for compatibility with the AWS S3 API and is tested with AIStor and AWS S3 for expected functionality and behavior.
AIStor provides no guarantees for other S3-compatible services, As their S3 API implementation is unknown and therefore unsupported.
While mc
commands may work as documented, any such usage is at your own risk.