DOCS-399: Resolve ILM related issues

source/includes/common-minio-tiering.rst

@@ -1,55 +1,8 @@
 .. 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 
+for the bucket. The following example configures transition after the
-objects on a calendar date *or* after a number of calendar days.
+specified number of calendar days:
-
-.. tab-set::
-
-   .. tab-item:: Transition after Calendar Date
-
-      .. code-block:: shell
-         :class: copyable
-
-         mc ilm add ALIAS/BUCKET \
-         --storage-class TIERNAME \
-         --transition-date DATE \
-         --noncurrentversion-transition-date NONCURRENT_DAYS
-
-      The example above specifies the following arguments:
-
-      .. list-table::
-         :header-rows: 1
-         :widths: 40 60
-         :width: 100%
-
-         * - Argument
-           - Description
-
-         * - :mc-cmd:`ALIAS <mc ilm add TARGET>`
-           - Specify the :mc:`alias <mc alias>` of the MinIO deployment for which
-             you are creating the lifecycle management rule.
-
-         * - :mc-cmd:`BUCKET <mc ilm add TARGET>`
-           - Specify the full path to the bucket for which you are
-             creating the lifecycle management rule.
-
-         * - :mc-cmd:`TIERNAME <mc ilm add storage-class>`
-           - The remote storage tier to which MinIO transitions objects. 
-             Specify the remote storage tier name created in the previous step.
-
-         * - :mc-cmd:`DATE <mc ilm add transition-date>`
-           - The ISO-8601-formatted calendar date after which MinIO marks an object
-             as eligible for transition.
-
-         * - :mc-cmd:`NONCURRENT_DAYS <mc ilm add noncurrentversion-transition-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
@@ -58,12 +11,13 @@ objects on a calendar date *or* after a number of calendar days.
    --storage-class TIERNAME \
    --transition-days DAYS \
    --noncurrentversion-transition-days NONCURRENT_DAYS
+   --noncurrentversion-transition-storage-class TIERNAME
 
 The example above specifies the following arguments:
 
 .. list-table::
    :header-rows: 1
-         :widths: 40 60
+   :widths: 30 70
    :width: 100%
 
    * - Argument
@@ -81,14 +35,21 @@ objects on a calendar date *or* after a number of calendar days.
      - The remote storage tier to which MinIO transitions objects. 
        Specify the remote storage tier name created in the previous step.
 
+       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:`DAYS <mc ilm add transition-days>`
      - The number of calendar days after which MinIO marks an object as 
        eligible for transition. 
 
    * - :mc-cmd:`NONCURRENT_DAYS <mc ilm add noncurrentversion-transition-days>`
      - The number of calendar days after which MinIO marks a noncurrent
-             object version as eligible for transition. Omit this value to
+       object version as eligible for transition. MinIO specifically measures
-             ignore noncurrent object versions.
+       the time since an object *became* non-current instead of the object
+       creation time. 
+       
+       Omit this value to ignore noncurrent object versions.
 
        This option has no effect on non-versioned buckets.
 

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 <mc ilm add TARGET>` with the 
-  :mc:`alias <mc alias>` of the S3-compatible host.
-
-- Replace :mc-cmd:`PATH <mc ilm add TARGET>` with the path to the bucket on the
-  S3-compatible host.
-
-- Replace :mc-cmd:`DATE <mc ilm add expiry-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
 -----------------------------------
 

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
+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
+:mc-cmd-option:`mc ilm add transition-days` command to transition objects to the
-create new transition rules on a bucket:
+remote tier after a specified number of calendar days.
-
-- :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.
 
 Versioned Buckets
 ~~~~~~~~~~~~~~~~~
@@ -68,7 +62,8 @@ on :ref:`versioned buckets <minio-bucket-versioning>`. 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:

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 <mc admin tier add 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 <mc admin tier add endpoint>`
      - 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 <mc ilm list TARGET>` with the :mc:`alias <mc alias>`
+- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the :mc:`alias <mc alias>`
   of the MinIO deployment.
 
-- Replace :mc-cmd:`PATH <mc ilm list TARGET>` with the name of the bucket for
+- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` with the name of the bucket for
   which to retrieve the configured lifecycle management rules.

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 <mc admin tier add 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 <mc admin tier add endpoint>`
      - 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 <mc ilm list TARGET>` with the :mc:`alias <mc alias>`
+- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the :mc:`alias <mc alias>`
   of the MinIO deployment.
 
-- Replace :mc-cmd:`PATH <mc ilm list TARGET>` with the name of the bucket for
+- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` with the name of the bucket for
   which to retrieve the configured lifecycle management rules.

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 <mc admin tier add TIER_NAME>`
-     - The name to associate with the new S3 remote storage tier. This value
+     - The name to associate with the new S3 remote storage tier. Specify the
-       is required in the next step.
+       name in all-caps, e.g. ``S3_TIER``. This value is required in the next
+       step.
 
    * - :mc-cmd:`HOSTNAME <mc admin tier add endpoint>`
      - 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 <mc ilm list TARGET>` with the :mc:`alias <mc alias>`
+- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the :mc:`alias <mc alias>`
   of the MinIO deployment.
 
-- Replace :mc-cmd:`PATH <mc ilm list TARGET>` with the name of the bucket for
+- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` with the name of the bucket for
   which to retrieve the configured lifecycle management rules.

source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst

@@ -163,6 +163,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:
 

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 <mc ilm add TARGET>` with the 
-  :mc:`alias <mc alias>` of the S3-compatible host.
-
-- Replace :mc-cmd:`PATH <mc ilm add TARGET>` with the path to the bucket on the
-  S3-compatible host.
-
-- Replace :mc-cmd:`DATE <mc ilm add expiry-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 <mc ilm list TARGET>` with the 
+- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the 
   :mc:`alias <mc alias>` of the S3-compatible host.
 
-- Replace :mc-cmd:`PATH <mc ilm list TARGET>` with the path to the bucket on the
+- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` 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
+      Exercise caution when using this option, as its behavior can result in
-      datetime marks all objects covered by the rule for deletion.
+      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 
+      <minio-lifecycle-management-tiering>`. 
+      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 <minio-lifecycle-management-tiering>`.
       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
-      <lifecycle-transition-general-considerations.html>` 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 
+      <minio-lifecycle-management-tiering>`. 
+      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 <minio-lifecycle-management-tiering>`.
       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
+      MinIO does *not* automatically migrate objects from the previously
-      is the Amazon S3 storage class to transition objects covered by the rule.
+      specified remote tier to the new remote tier. MinIO continues to
-      See :s3-docs:`Transition objects using Amazon S3 Lifecycle
+      route requests for objects stored on the old remote tier.
-      <lifecycle-transition-general-considerations.html>` for more information
-      on S3 storage classes.
 
    .. 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`