diff --git a/source/includes/common-minio-tiering.rst b/source/includes/common-minio-tiering.rst index 92b3a7b9..cef1069e 100644 --- a/source/includes/common-minio-tiering.rst +++ b/source/includes/common-minio-tiering.rst @@ -1,96 +1,57 @@ .. start-create-transition-rule-desc Use the :mc-cmd:`mc ilm add` command to create a new transition rule -for the bucket. The following tabs contain examples for transitioning -objects on a calendar date *or* after a number of calendar days. +for the bucket. The following example configures transition after the +specified number of calendar days: -.. tab-set:: +.. code-block:: shell + :class: copyable - .. tab-item:: Transition after Calendar Date + mc ilm add ALIAS/BUCKET \ + --storage-class TIERNAME \ + --transition-days DAYS \ + --noncurrentversion-transition-days NONCURRENT_DAYS + --noncurrentversion-transition-storage-class TIERNAME - .. code-block:: shell - :class: copyable +The example above specifies the following arguments: - mc ilm add ALIAS/BUCKET \ - --storage-class TIERNAME \ - --transition-date DATE \ - --noncurrentversion-transition-date NONCURRENT_DAYS +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% - The example above specifies the following arguments: + * - Argument + - Description - .. list-table:: - :header-rows: 1 - :widths: 40 60 - :width: 100% + * - :mc-cmd:`ALIAS ` + - Specify the :mc:`alias ` of the MinIO deployment for which + you are creating the lifecycle management rule. - * - Argument - - Description + * - :mc-cmd:`BUCKET ` + - Specify the full path to the bucket for which you are + creating the lifecycle management rule. - * - :mc-cmd:`ALIAS ` - - Specify the :mc:`alias ` of the MinIO deployment for which - you are creating the lifecycle management rule. + * - :mc-cmd:`TIERNAME ` + - The remote storage tier to which MinIO transitions objects. + Specify the remote storage tier name created in the previous step. - * - :mc-cmd:`BUCKET ` - - Specify the full path to the bucket for which you are - creating the lifecycle management rule. + If you want to transition noncurrent object versions to a distinct + remote tier, specify a different tier name for + :mc-cmd-option:`~mc ilm add noncurrentversion-transition-storage-class`. - * - :mc-cmd:`TIERNAME ` - - The remote storage tier to which MinIO transitions objects. - Specify the remote storage tier name created in the previous step. + * - :mc-cmd:`DAYS ` + - The number of calendar days after which MinIO marks an object as + eligible for transition. - * - :mc-cmd:`DATE ` - - The ISO-8601-formatted calendar date after which MinIO marks an object - as eligible for transition. + * - :mc-cmd:`NONCURRENT_DAYS ` + - The number of calendar days after which MinIO marks a noncurrent + object version as eligible for transition. MinIO specifically measures + the time since an object *became* non-current instead of the object + creation time. + + Omit this value to ignore noncurrent object versions. - * - :mc-cmd:`NONCURRENT_DAYS ` - - The number of calendar days after which MinIO marks a noncurrent - object version as eligible for transition. Omit this value to - ignore noncurrent object versions. - - This option has no effect on non-versioned buckets. - - .. tab-item:: Transition after Calendar Days - - .. code-block:: shell - :class: copyable - - mc ilm add ALIAS/BUCKET \ - --storage-class TIERNAME \ - --transition-days DAYS \ - --noncurrentversion-transition-days NONCURRENT_DAYS - - The example above specifies the following arguments: - - .. list-table:: - :header-rows: 1 - :widths: 40 60 - :width: 100% - - * - Argument - - Description - - * - :mc-cmd:`ALIAS ` - - Specify the :mc:`alias ` of the MinIO deployment for which - you are creating the lifecycle management rule. - - * - :mc-cmd:`BUCKET ` - - Specify the full path to the bucket for which you are - creating the lifecycle management rule. - - * - :mc-cmd:`TIERNAME ` - - The remote storage tier to which MinIO transitions objects. - Specify the remote storage tier name created in the previous step. - - * - :mc-cmd:`DAYS ` - - The number of calendar days after which MinIO marks an object as - eligible for transition. - - * - :mc-cmd:`NONCURRENT_DAYS ` - - The number of calendar days after which MinIO marks a noncurrent - object version as eligible for transition. Omit this value to - ignore noncurrent object versions. - - This option has no effect on non-versioned buckets. + This option has no effect on non-versioned buckets. .. end-create-transition-rule-desc diff --git a/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst b/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst index 20f1f21a..e0d08d20 100644 --- a/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst +++ b/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst @@ -59,27 +59,6 @@ transition lifecycle management rules on any bucket in the cluster:. :language: json :class: copyable -Expire Objects after Calendar Date ----------------------------------- - -Use :mc-cmd:`mc ilm add` with :mc-cmd-option:`~mc ilm add expiry-date` to -expire bucket contents after a specific date. - -.. code-block:: shell - :class: copyable - - mc ilm add ALIAS/PATH --expiry-date "DATE" - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket on the - S3-compatible host. - -- Replace :mc-cmd:`DATE ` with the calendar date after - which to expire the object. For example, specify "2021-01-01" to expire - objects after January 1st, 2021. - Expire Objects after Number of Days ----------------------------------- diff --git a/source/lifecycle-management/lifecycle-management-overview.rst b/source/lifecycle-management/lifecycle-management-overview.rst index 1204a52c..ba76c77e 100644 --- a/source/lifecycle-management/lifecycle-management-overview.rst +++ b/source/lifecycle-management/lifecycle-management-overview.rst @@ -49,15 +49,9 @@ objects. Object transition is *not* a replacement for backup/recovery strategies such as :ref:`minio-bucket-replication`. Use the :mc-cmd:`mc admin tier` command to create a remote target for tiering -data to a supported Cloud Service Provider object storage You can then use the -:mc-cmd:`mc ilm add` command with one of the following commandline options to -create new transition rules on a bucket: - -- :mc-cmd-option:`mc ilm add transition-date` to transition objects after - a specified calendar date. - -- :mc-cmd-option:`mc ilm add transition-days` to transition object after - a specified number of calendar days. +data to a supported Cloud Service Provider object storage. You can then use the +:mc-cmd-option:`mc ilm add transition-days` command to transition objects to the +remote tier after a specified number of calendar days. Versioned Buckets ~~~~~~~~~~~~~~~~~ @@ -68,7 +62,8 @@ on :ref:`versioned buckets `. Specifically, MinIO by default applies the transition operation to the *current* object version. To transition noncurrent object versions, specify the -:mc-cmd-option:`~mc ilm add noncurrentversion-transition-days` option +:mc-cmd-option:`~mc ilm add noncurrentversion-transition-days` and +:mc-cmd-option:`~mc ilm add noncurrentversion-transition-storage-class` options when creating the transition rule. .. _minio-lifecycle-management-expiration: diff --git a/source/lifecycle-management/transition-objects-to-azure.rst b/source/lifecycle-management/transition-objects-to-azure.rst index 5e97e30d..0570b7a1 100644 --- a/source/lifecycle-management/transition-objects-to-azure.rst +++ b/source/lifecycle-management/transition-objects-to-azure.rst @@ -141,7 +141,7 @@ The example above uses the following arguments: .. list-table:: :header-rows: 1 - :widths: 40 60 + :widths: 30 70 :width: 100% * - Argument @@ -153,7 +153,8 @@ The example above uses the following arguments: * - :mc-cmd:`TIER_NAME ` - The name to associate with the new :abbr:`Azure (Microsoft Azure)` blob - remote storage tier. This value is required in the next step. + remote storage tier. Specify the name in all-caps, e.g. ``AZURE_TIER``. + This value is required in the next step. * - :mc-cmd:`HOSTNAME ` - The URL endpoint for the :abbr:`Azure (Microsoft Azure)` storage @@ -194,16 +195,16 @@ The example above uses the following arguments: 3) Verify the Transition Rule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :mc-cmd:`mc ilm list` command to review the configured transition +Use the :mc-cmd:`mc ilm ls` command to review the configured transition rules: .. code-block:: shell :class: copyable - mc ilm list ALIAS/PATH --transition + mc ilm ls ALIAS/PATH --transition -- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment. -- Replace :mc-cmd:`PATH ` with the name of the bucket for +- Replace :mc-cmd:`PATH ` with the name of the bucket for which to retrieve the configured lifecycle management rules. diff --git a/source/lifecycle-management/transition-objects-to-gcs.rst b/source/lifecycle-management/transition-objects-to-gcs.rst index 728e17ba..6ce20339 100644 --- a/source/lifecycle-management/transition-objects-to-gcs.rst +++ b/source/lifecycle-management/transition-objects-to-gcs.rst @@ -130,7 +130,7 @@ The example above uses the following arguments: .. list-table:: :header-rows: 1 - :widths: 40 60 + :widths: 30 70 :width: 100% * - Argument @@ -142,7 +142,8 @@ The example above uses the following arguments: * - :mc-cmd:`TIER_NAME ` - The name to associate with the new :abbr:`GCS (Google Cloud Storage)` - remote storage tier. This value is required in the next step. + remote storage tier. Specify the name in all-caps, e.g. ``GCS_TIER``. + This value is required in the next step. * - :mc-cmd:`HOSTNAME ` - The URL endpoint for the :abbr:`GCS (Google Cloud Storage)` storage @@ -180,16 +181,16 @@ The example above uses the following arguments: 3) Verify the Transition Rule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :mc-cmd:`mc ilm list` command to review the configured transition +Use the :mc-cmd:`mc ilm ls` command to review the configured transition rules: .. code-block:: shell :class: copyable - mc ilm list ALIAS/PATH --transition + mc ilm ls ALIAS/PATH --transition -- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment. -- Replace :mc-cmd:`PATH ` with the name of the bucket for +- Replace :mc-cmd:`PATH ` with the name of the bucket for which to retrieve the configured lifecycle management rules. diff --git a/source/lifecycle-management/transition-objects-to-s3.rst b/source/lifecycle-management/transition-objects-to-s3.rst index 6c07a9c1..62ad8a25 100644 --- a/source/lifecycle-management/transition-objects-to-s3.rst +++ b/source/lifecycle-management/transition-objects-to-s3.rst @@ -141,7 +141,7 @@ The example above uses the following arguments: .. list-table:: :header-rows: 1 - :widths: 40 60 + :widths: 30 70 :width: 100% * - Argument @@ -152,8 +152,9 @@ The example above uses the following arguments: the S3 remote tier. * - :mc-cmd:`TIER_NAME ` - - The name to associate with the new S3 remote storage tier. This value - is required in the next step. + - The name to associate with the new S3 remote storage tier. Specify the + name in all-caps, e.g. ``S3_TIER``. This value is required in the next + step. * - :mc-cmd:`HOSTNAME ` - The URL endpoint for the S3 storage backend. @@ -198,16 +199,16 @@ The example above uses the following arguments: 3) Verify the Transition Rule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :mc-cmd:`mc ilm list` command to review the configured transition +Use the :mc-cmd:`mc ilm ls` command to review the configured transition rules: .. code-block:: shell :class: copyable - mc ilm list ALIAS/PATH --transition + mc ilm ls ALIAS/PATH --transition -- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment. -- Replace :mc-cmd:`PATH ` with the name of the bucket for +- Replace :mc-cmd:`PATH ` with the name of the bucket for which to retrieve the configured lifecycle management rules. diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst b/source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst index 5a4b2248..4164902c 100644 --- a/source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst +++ b/source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst @@ -162,6 +162,8 @@ Syntax The name to associate with the new remote tier. The name *must* be unique across all configured tiers on the MinIO cluster. + + You **must** specify the tier in all-caps, e.g. ``WARM_TIER``. .. mc-cmd:: endpoint :option: diff --git a/source/reference/minio-cli/minio-mc/mc-ilm.rst b/source/reference/minio-cli/minio-mc/mc-ilm.rst index 8df77c62..928960ff 100644 --- a/source/reference/minio-cli/minio-mc/mc-ilm.rst +++ b/source/reference/minio-cli/minio-mc/mc-ilm.rst @@ -36,34 +36,13 @@ Expiry vs Transition MinIO supports specifying both expiry and transition rules in the same bucket or bucket prefix. MinIO can execute an expiration rule on an object regardless of its transition status. Use -:mc-cmd:`mc ilm list` to review the currently configured object lifecycle +:mc-cmd:`mc ilm ls` to review the currently configured object lifecycle management rules for any potential interactions between expiry and transition rules. Examples -------- -Expire Bucket Contents After Specific Date -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use :mc-cmd:`mc ilm add` with :mc-cmd-option:`~mc ilm add expiry-date` to -expire bucket contents after a specific date. - -.. code-block:: shell - :class: copyable - - mc ilm add ALIAS/PATH --expiry-date "DATE" - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket on the - S3-compatible host. - -- Replace :mc-cmd:`DATE ` with the calendar date after - which to expire the object. For example, specify "2021-01-01" to expire - objects after January 1st, 2021. - Expire Bucket Contents After Number of Days ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -88,17 +67,17 @@ expire bucket contents a number of days after object creation: List Bucket Lifecycle Management Rules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use :mc-cmd:`mc ilm list` to list a bucket's lifecycle management rules: +Use :mc-cmd:`mc ilm ls` to list a bucket's lifecycle management rules: .. code-block:: shell :class: copyable - mc ilm list ALIAS/PATH + mc ilm ls ALIAS/PATH -- Replace :mc-cmd:`ALIAS ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the S3-compatible host. -- Replace :mc-cmd:`PATH ` with the path to the bucket on the +- Replace :mc-cmd:`PATH ` with the path to the bucket on the S3-compatible host. Remove a Bucket Lifecycle Management Rule @@ -124,7 +103,7 @@ Use :mc-cmd:`mc ilm remove` to remove a bucket lifecycle management rule: Syntax ------ -.. mc-cmd:: list +.. mc-cmd:: ls :fullpath: Lists the current lifecycle management rules of the specified bucket. The @@ -133,7 +112,7 @@ Syntax .. code-block:: shell :class: copyable - mc ilm list TARGET [FLAGS] + mc ilm ls TARGET [FLAGS] The subcommand supports the following arguments: @@ -147,7 +126,7 @@ Syntax .. code-block:: shell - mc ilm list play/mybucket + mc ilm ls play/mybucket .. mc-cmd:: expiry :option: @@ -222,8 +201,13 @@ Syntax after being created. MinIO marks the object for deletion once the system host datetime passes that calendar date. - Specifying a calendar date that is *prior* to the current system host - datetime marks all objects covered by the rule for deletion. + Exercise caution when using this option, as its behavior can result in + immediate expiration of uploaded objects. Any objects created *after* + the specified expiration date are automatically eligible for expiration. + Similarly, specifying a calendar date that is *prior* to the current + system host datetime marks all objects covered by the rule for deletion. + Consider immediately removing any ILM rule using this option once the + specified calendar date has passed. For versioned buckets, the expiry rule applies only to the *current* object version. Use the @@ -304,11 +288,21 @@ Syntax :mc-cmd-option:`~mc ilm add storage-class` once the system host datetime passes that calendar date. + Exercise caution when using this option, as its behavior can result in + immediate transition of uploaded objects. Any objects created *after* + the specified transition date are automatically eligible for transition. + Similarly, specifying a calendar date that is *prior* to the current + system host datetime marks all objects covered by the rule for transition. + Consider immediately removing any ILM rule using this option once the + specified calendar date has passed. + For versioned buckets, the transition rule applies only to the *current* object version. Use the :mc-cmd-option:`~mc ilm add noncurrentversion-transition-days` option to apply transition behavior to noncurrent object versions. + Requires specifying :mc-cmd-option:`~mc ilm add storage-class`. + MinIO 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 @@ -327,6 +321,8 @@ Syntax :mc-cmd-option:`~mc ilm add noncurrentversion-transition-days` option to apply transition behavior to noncurrent object versions. + Requires specifying :mc-cmd-option:`~mc ilm add storage-class`. + MinIO 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 @@ -342,7 +338,8 @@ Syntax :mc-cmd-option:`~mc ilm add storage-class` once the system host datetime passes that calendar date. - This option has no effect on non-versioned buckets. + This option has no effect on non-versioned buckets. Requires specifying + :mc-cmd-option:`~mc ilm add noncurrentversion-transition-storage-class`. This option has the same behavior as the S3 ``NoncurrentVersionTransition`` action. @@ -352,6 +349,14 @@ Syntax limited system resources may delay application of lifecycle management rules. See :ref:`minio-lifecycle-management-scanner` for more information. + .. mc-cmd:: noncurrentversion-transition-storage-class + :option: + + The remote storage tier to which MinIO + :ref:`transitions noncurrent objects versions + `. + Specify a remote storage tier created by :mc-cmd:`mc admin tier`. + .. mc-cmd:: storage-class :option: @@ -359,12 +364,6 @@ Syntax :ref:`transition objects `. Specify a remote storage tier created by :mc-cmd:`mc admin tier`. - If using :mc-cmd:`mc ilm add` against an Amazon S3 service, this argument - is the Amazon S3 storage class to transition objects covered by the rule. - See :s3-docs:`Transition objects using Amazon S3 Lifecycle - ` for more information - on S3 storage classes. - .. mc-cmd:: disable :option: @@ -405,7 +404,7 @@ Syntax *Required* - The unique ID of the rule. Use :mc-cmd:`mc ilm list` to list bucket rules + The unique ID of the rule. Use :mc-cmd:`mc ilm ls` to list bucket rules and retrieve the ``id`` for the rule you want to modify. .. mc-cmd:: tags @@ -450,6 +449,14 @@ Syntax The number of days to retain an object after being created. MinIO marks the object for deletion after the specified number of days pass. + Exercise caution when using this option, as its behavior can result in + immediate expiration of uploaded objects. Any objects created *after* + the specified expiration date are automatically eligible for expiration. + Similarly, specifying a calendar date that is *prior* to the current + system host datetime marks all objects covered by the rule for deletion. + Consider immediately removing any ILM rule using this option once the + specified calendar date has passed. + For versioned buckets, the expiry rule applies only to the *current* object version. Use the :mc-cmd-option:`~mc ilm edit noncurrentversion-expiration-days` option @@ -508,11 +515,21 @@ Syntax :mc-cmd-option:`~mc ilm edit storage-class` once the system host datetime passes that calendar date. + Exercise caution when using this option, as its behavior can result in + immediate transition of uploaded objects. Any objects created *after* + the specified transition date are automatically eligible for transition. + Similarly, specifying a calendar date that is *prior* to the current + system host datetime marks all objects covered by the rule for transition. + Consider immediately removing any ILM rule using this option once the + specified calendar date has passed. + For versioned buckets, the transition rule applies only to the *current* object version. Use the :mc-cmd-option:`~mc ilm edit noncurrentversion-transition-days` option to apply transition behavior to noncurrent object versions. + Requires specifying :mc-cmd-option:`~mc ilm edit storage-class`. + MinIO 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 @@ -531,6 +548,8 @@ Syntax :mc-cmd-option:`~mc ilm edit noncurrentversion-transition-days` option to apply transition behavior to noncurrent object versions. + Requires specifying :mc-cmd-option:`~mc ilm edit storage-class`. + MinIO 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 @@ -546,7 +565,8 @@ Syntax :mc-cmd-option:`~mc ilm edit storage-class` once the system host datetime passes that calendar date. - This option has no effect on non-versioned buckets. + This option has no effect on non-versioned buckets. Requires specifying + :mc-cmd-option:`~mc ilm edit noncurrentversion-transition-storage-class`. This option has the same behavior as the S3 ``NoncurrentVersionTransition`` action. @@ -556,6 +576,18 @@ Syntax limited system resources may delay application of lifecycle management rules. See :ref:`minio-lifecycle-management-scanner` for more information. + .. mc-cmd:: noncurrentversion-transition-storage-class + :option: + + The remote storage tier to which MinIO + :ref:`transitions noncurrent objects versions + `. + Specify a remote storage tier created by :mc-cmd:`mc admin tier`. + + MinIO does *not* automatically migrate objects from the previously + specified remote tier to the new remote tier. MinIO continues to + route requests for objects stored on the old remote tier. + .. mc-cmd:: storage-class :option: @@ -563,11 +595,9 @@ Syntax :ref:`transition objects `. Specify a remote storage tier created by :mc-cmd:`mc admin tier`. - If using :mc-cmd:`mc ilm edit` against an Amazon S3 service, this argument - is the Amazon S3 storage class to transition objects covered by the rule. - See :s3-docs:`Transition objects using Amazon S3 Lifecycle - ` for more information - on S3 storage classes. + MinIO does *not* automatically migrate objects from the previously + specified remote tier to the new remote tier. MinIO continues to + route requests for objects stored on the old remote tier. .. mc-cmd:: disable :option: @@ -604,7 +634,7 @@ Syntax *Required* - The unique ID of the rule. Use :mc-cmd:`mc ilm list` to list bucket rules + The unique ID of the rule. Use :mc-cmd:`mc ilm ls` to list bucket rules and retrieve the ``id`` for the rule you want to remove. Mutually exclusive with :mc-cmd-option:`mc ilm remove all`