From b485e69a5fa4eeabe36072da781935ddf4d59195 Mon Sep 17 00:00:00 2001 From: debadair Date: Thu, 8 Nov 2018 15:26:27 -0800 Subject: [PATCH] ILM API ref edits (#35112) * [DOCS] ILM API Ref edits * [DOCS] Fixed endpoint for DELETE policy. * [DOCS] Removed comparison to setting index.lifecycle.name to null. * [DOCS] Fixed xrefs to explain API. --- .../ilm/apis/delete-lifecycle.asciidoc | 24 ++--- docs/reference/ilm/apis/explain.asciidoc | 102 ++++++++---------- .../reference/ilm/apis/get-lifecycle.asciidoc | 30 +++--- docs/reference/ilm/apis/get-status.asciidoc | 30 +++--- docs/reference/ilm/apis/ilm-api.asciidoc | 2 +- .../apis/ilm-cluster-mgt-privilege.asciidoc | 2 + .../ilm/apis/ilm-index-mgt-privilege.asciidoc | 2 + docs/reference/ilm/apis/move-to-step.asciidoc | 50 +++++---- .../reference/ilm/apis/put-lifecycle.asciidoc | 31 +++--- .../reference/ilm/apis/remove-policy.asciidoc | 29 +++-- docs/reference/ilm/apis/retry-policy.asciidoc | 27 ++--- docs/reference/ilm/apis/start.asciidoc | 26 ++--- docs/reference/ilm/apis/stop.asciidoc | 31 +++--- docs/reference/ilm/index.asciidoc | 7 +- .../ilm/update-lifecycle-policy.asciidoc | 9 +- docs/reference/rest-api/timeoutparms.asciidoc | 11 ++ 16 files changed, 186 insertions(+), 227 deletions(-) create mode 100644 docs/reference/ilm/apis/ilm-cluster-mgt-privilege.asciidoc create mode 100644 docs/reference/ilm/apis/ilm-index-mgt-privilege.asciidoc create mode 100644 docs/reference/rest-api/timeoutparms.asciidoc diff --git a/docs/reference/ilm/apis/delete-lifecycle.asciidoc b/docs/reference/ilm/apis/delete-lifecycle.asciidoc index 3c8b6c397c0..510d02ae579 100644 --- a/docs/reference/ilm/apis/delete-lifecycle.asciidoc +++ b/docs/reference/ilm/apis/delete-lifecycle.asciidoc @@ -6,15 +6,17 @@ Delete Policy ++++ -Deletes an existing lifecycle policy +Deletes a lifecycle policy. ==== Request -`DELETE _ilm/policy/` +`DELETE _ilm/policy/` ==== Description -Deletes an existing lifecycle policy +Deletes the specified lifecycle policy definition. You cannot delete policies +that are currently in use. If the policy is being used to manage any indices, +the request fails and returns an error. ==== Path Parameters @@ -23,21 +25,15 @@ Deletes an existing lifecycle policy ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - DELETE operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-cluster-mgt-privilege.asciidoc[] ==== Examples -The following example deletes an existing policy named `my_policy`: +The following example deletes `my_policy`: ////////////////////////// @@ -77,7 +73,7 @@ DELETE _ilm/policy/my_policy // CONSOLE // TEST[continued] -If the request does not encounter errors, you receive the following result: +When the policy is successfully deleted, you receive the following result: [source,js] -------------------------------------------------- diff --git a/docs/reference/ilm/apis/explain.asciidoc b/docs/reference/ilm/apis/explain.asciidoc index 95daf0bda1f..31d89a5bf0d 100644 --- a/docs/reference/ilm/apis/explain.asciidoc +++ b/docs/reference/ilm/apis/explain.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="basic"] -[[ilm-explain]] +[[ilm-explain-lifecycle]] === Explain Lifecycle API ++++ Explain Lifecycle ++++ -Shows the current lifecycle status for an index. +Shows an index's current lifecycle status. ==== Request @@ -14,11 +14,10 @@ Shows the current lifecycle status for an index. ==== Description -This API returns information relating to the current lifecycle state of an -index. This includes information such as the currently executing phase, action, -and step and the timestamp when the index entered them. It also shows the -definition of the current phase that is being run and in the event that there -has been a failure, information regarding the failure. +Retrieves information about the index's current lifecycle state, such as +the currently executing phase, action, and step. Shows when the index entered +each one, the definition of the running phase, and information +about any failures. ==== Path Parameters @@ -27,21 +26,15 @@ has been a failure, information regarding the failure. ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - GET operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-index-mgt-privilege.asciidoc[] ==== Examples -The following example retrieves the lifecycle state for the index `my_index`: +The following example retrieves the lifecycle state of `my_index`: ////////////////////////// @@ -91,7 +84,8 @@ GET my_index/_ilm/explain // CONSOLE // TEST[continued] -When the index is first taken over by ILM you will see a response like the following: +When management of the index is first taken over by ILM, `explain` shows +that the index is managed and in the `new` phase: [source,js] -------------------------------------------------- @@ -102,12 +96,12 @@ When the index is first taken over by ILM you will see a response like the follo "managed": true, <1> "policy": "my_policy", <2> "lifecycle_date_millis": 1538475653281, <3> - "phase": "new", <4> - "phase_time_millis": 1538475653317, <5> - "action": "complete", <6> - "action_time_millis": 1538475653317, <7> - "step": "complete", <8> - "step_time_millis": 1538475653317 <9> + "phase": "new", + "phase_time_millis": 1538475653317, <4> + "action": "complete", + "action_time_millis": 1538475653317, <5> + "step": "complete", + "step_time_millis": 1538475653317 <6> } } } @@ -121,17 +115,14 @@ When the index is first taken over by ILM you will see a response like the follo ILM the other fields will not be shown <2> The name of the policy which ILM is using for this index <3> The timestamp used for the `min_age` -<4> The current phase -<5> The timestamp for when the index entered the current phase -<6> The current action -<7> The timestamp for when the index entered the current action -<8> The current step -<9> The timestamp for when the index entered the current step +<4> When the index entered the current phase +<5> When the index entered the current action +<6> When the index entered the current step -When the policy is running on the index the response will contain a -`phase_execution` object that describes the exact phase that is being run. +Once the policy is running on the index, the response includes a +`phase_execution` object that shows the definition of the current phase. Changes to the underlying policy will not affect this index until the current -phase definition has been completely executed. +phase completes. [source,js] -------------------------------------------------- @@ -152,9 +143,9 @@ phase definition has been completely executed. "step": "attempt_rollover", "step_time_millis": 1538475653317, "step_time": "2018-10-15T13:45:22.577Z", - "phase_execution": { <1> - "policy": "my_lifecycle3", <2> - "phase_definition": { <3> + "phase_execution": { + "policy": "my_lifecycle3", + "phase_definition": { <1> "min_age": "0ms", "actions": { "rollover": { @@ -162,9 +153,9 @@ phase definition has been completely executed. } } }, - "version": 3, <4> - "modified_date": "2018-10-15T13:21:41.576Z", <5> - "modified_date_in_millis": 1539609701576 <6> + "version": 3, <2> + "modified_date": "2018-10-15T13:21:41.576Z", <3> + "modified_date_in_millis": 1539609701576 <4> } } } @@ -172,16 +163,14 @@ phase definition has been completely executed. -------------------------------------------------- // CONSOLE // TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test] -<1> The phase execution information for this index in its current phase -<2> The policy that this phase definition was loaded from -<3> The phase definition itself. This is the JSON for the phase loaded from the -policy at the time the index entered the current phase -<4> The version of the policy at the time the phase definition was loaded -<5> The last modified date of the policy at the time the phase definition was loaded -<6> The last modified epoch time of the policy at the time the phase definition was loaded +<1> The JSON phase definition loaded from the specified policy when the index +entered this phase +<2> The version of the policy that was loaded +<3> The date the loaded policy was last modified +<4> The epoch time when the loaded policy was last modified - -If the policy is waiting for a step to complete for the index, the response will contain step information such as: +If {ILM} is waiting for a step to complete, the response includes status +information for the step that's being performed on the index. [source,js] -------------------------------------------------- @@ -236,14 +225,12 @@ If the policy is waiting for a step to complete for the index, the response will -------------------------------------------------- // CONSOLE // TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test] -<1> `step_info` shows information about what ILM is waiting for on this index. -In this case we are waiting for all shard copies of the index to be active. +<1> Status of the step that's in progress. -If the index is in the ERROR step, something has gone wrong when executing a -step in the policy and will need to be investigated and resolved for the index -to make progress. TO help determine how to resolve the error the explain response -will show the step that failed in `failed_step`, and the information on the error -that occurred in `step_info`. +If the index is in the ERROR step, something went wrong while executing a +step in the policy and and you will need to take action for the index to proceed +to the next step. To help you diagnose the problem, the explain response shows +the step that failed and the step info provides information about the error. [source,js] -------------------------------------------------- @@ -291,6 +278,5 @@ that occurred in `step_info`. -------------------------------------------------- // CONSOLE // TESTRESPONSE[skip:not possible to get the cluster into this state in a docs test] -<1> The step that caused an error -<2> Information on the error that occurred. In this case the next index already -existed when the rollover operation was performed +<1> The step that caused the error +<2> What went wrong diff --git a/docs/reference/ilm/apis/get-lifecycle.asciidoc b/docs/reference/ilm/apis/get-lifecycle.asciidoc index dbc8a572903..4b9b2a3bd3b 100644 --- a/docs/reference/ilm/apis/get-lifecycle.asciidoc +++ b/docs/reference/ilm/apis/get-lifecycle.asciidoc @@ -6,18 +6,17 @@ Get Policy ++++ -Retrieves an existing policy +Retrieves a lifecycle policy. ==== Request `GET _ilm/policy` -`GET _ilm/policy/` +`GET _ilm/policy/` ==== Description -This API returns a policy definition along with some of its metadata like -its last modified date and version. If no path parameters are provided, then -all the policies defined will be returned. +Returns the specified policy definition. Includes the policy version and last +modified date. If no policy is specified, returns all defined policies. ==== Path Parameters @@ -26,21 +25,15 @@ all the policies defined will be returned. ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - GET operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-cluster-mgt-privilege.asciidoc[] ==== Examples -The following example retrieves the policy named `my_policy`: +The following example retrieves `my_policy`: ////////////////////////// @@ -80,7 +73,8 @@ GET _ilm/policy // CONSOLE // TEST[continued] -If the request does not encounter errors, you receive the following result: + +If the request succeeds, the body of the response contains the policy definition: [source,js] -------------------------------------------------- @@ -111,5 +105,5 @@ If the request does not encounter errors, you receive the following result: -------------------------------------------------- // CONSOLE // TESTRESPONSE[s/"modified_date": 82392349/"modified_date": $body.my_policy.modified_date/] -<1> The version of the policy. This is increased whenever the policy is updated -<2> The timestamp when this policy was last modified +<1> The policy version is incremented whenever the policy is updated +<2> When this policy was last modified diff --git a/docs/reference/ilm/apis/get-status.asciidoc b/docs/reference/ilm/apis/get-status.asciidoc index 8f5d2289ff2..4406b805fb5 100644 --- a/docs/reference/ilm/apis/get-status.asciidoc +++ b/docs/reference/ilm/apis/get-status.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="basic"] [[ilm-get-status]] -=== Get ILM Status API +=== Get {ILM} Status API ++++ -Get ILM Status +Get {ILM} Status ++++ -Gets the current status for ILM. +Retrieves the current {ilm} status. ==== Request @@ -14,28 +14,22 @@ Gets the current status for ILM. ==== Description -This API will return the current status of the ILM plugin. The response contains -a `operation_mode` field which shows whether the ILM plugin is `STARTED`, `STOPPING` -or `STOPPED`. This `operation_mode` is controlled by the <> -and <> APIs. +Returns the status of the {ILM} plugin. The `operation_mode` field in the +response shows one of three states: `STARTED`, `STOPPING`, +or `STOPPED`. You can change the status of the {ILM} plugin with the +<> and <> APIs. ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - get operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-cluster-mgt-privilege.asciidoc[] ==== Examples -The following example stops the ILM plugin. +The following example gets the {ILM} plugin status. [source,js] -------------------------------------------------- @@ -43,7 +37,7 @@ GET _ilm/status -------------------------------------------------- // CONSOLE -If the request does not encounter errors, you receive the following result: +If the request succeeds, the body of the response shows the operation mode: [source,js] -------------------------------------------------- diff --git a/docs/reference/ilm/apis/ilm-api.asciidoc b/docs/reference/ilm/apis/ilm-api.asciidoc index 49c7d2155d5..351ff44f41f 100644 --- a/docs/reference/ilm/apis/ilm-api.asciidoc +++ b/docs/reference/ilm/apis/ilm-api.asciidoc @@ -25,7 +25,7 @@ You can use the following APIs to manage policies on indices. * <> * <> * <> -* <> +* <> include::put-lifecycle.asciidoc[] diff --git a/docs/reference/ilm/apis/ilm-cluster-mgt-privilege.asciidoc b/docs/reference/ilm/apis/ilm-cluster-mgt-privilege.asciidoc new file mode 100644 index 00000000000..eef1433a9c0 --- /dev/null +++ b/docs/reference/ilm/apis/ilm-cluster-mgt-privilege.asciidoc @@ -0,0 +1,2 @@ +You must have the cluster `manage` privilege to use this API. +For more information, see {stack-ov}/security-privileges.html[Security Privileges]. diff --git a/docs/reference/ilm/apis/ilm-index-mgt-privilege.asciidoc b/docs/reference/ilm/apis/ilm-index-mgt-privilege.asciidoc new file mode 100644 index 00000000000..c2a3e3fddb5 --- /dev/null +++ b/docs/reference/ilm/apis/ilm-index-mgt-privilege.asciidoc @@ -0,0 +1,2 @@ +You must have the `manage` privilege on the indices being managed to use this API. +For more information, see {stack-ov}/security-privileges.html[Security Privileges]. diff --git a/docs/reference/ilm/apis/move-to-step.asciidoc b/docs/reference/ilm/apis/move-to-step.asciidoc index c34b800856c..854b1ab317d 100644 --- a/docs/reference/ilm/apis/move-to-step.asciidoc +++ b/docs/reference/ilm/apis/move-to-step.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="basic"] [[ilm-move-to-step]] -=== Move To Step API +=== Move to Lifecycle Step API ++++ -Move To Step +Move to Step ++++ -Moves a managed index into a specific execution step its policy +Triggers execution of a specific step in the lifecycle policy. ==== Request @@ -14,13 +14,18 @@ Moves a managed index into a specific execution step its policy ==== Description -WARNING: This is an expert API that may lead to unintended data loss. When used, -an index's policy will begin executing at the specified step. It will execute -the step specified even if it has already executed it. Since this is a, potentionally, -dangerous action, specifying both the current step and next step to move to is -required in the body of the request. +WARNING: This operation can result in the loss of data. Manually moving an index +into a specific step executes that step even if it has already been performed. +This is a potentially destructive action and this should be considered an expert +level API. -This API changes the current step for the specified index to the step supplied in the body of the request +Manually moves an index into the specified step and executes that step. +You must specify both the current step and the step to be executed in the +body of the request. + +The request will fail if the current step does not match the step currently +being executed for the index. This is to prevent the index from being moved from +an unexpected step into the next step. ==== Path Parameters @@ -29,22 +34,16 @@ This API changes the current step for the specified index to the step supplied i ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - move operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-index-mgt-privilege.asciidoc[] ==== Examples -The following example moves the index `my_index` from the initial step to the -forcemerge step: +The following example moves `my_index` from the initial step to the +`forcemerge` step: ////////////////////////// @@ -102,10 +101,10 @@ POST _ilm/move/my_index -------------------------------------------------- // CONSOLE // TEST[continued] -<1> The step that the index is currently expected to be executing -<2> The step that the index should move to when executing this request +<1> The step that the index is expected to be in +<2> The step that you want to execute -If the request does not encounter errors, you receive the following result: +If the request succeeds, you receive the following result: [source,js] -------------------------------------------------- @@ -116,6 +115,5 @@ If the request does not encounter errors, you receive the following result: // CONSOLE // TESTRESPONSE -NOTE: An error will be returned if the index is now longer executing the step -specified in `current_step`. This is so the index is not moved from an -unexpected step into the `next_step`. +The request will fail if the index is not in the `new` phase as specified +by the `current_step`. diff --git a/docs/reference/ilm/apis/put-lifecycle.asciidoc b/docs/reference/ilm/apis/put-lifecycle.asciidoc index 36650078db6..565598e75cd 100644 --- a/docs/reference/ilm/apis/put-lifecycle.asciidoc +++ b/docs/reference/ilm/apis/put-lifecycle.asciidoc @@ -1,25 +1,24 @@ [role="xpack"] [testenv="basic"] [[ilm-put-lifecycle]] -=== Put Lifecycle Policy API +=== Create Lifecycle Policy API ++++ -Put Policy +Create Policy ++++ -Creates or updates an ILM Policy +Creates or updates lifecycle policy. ==== Request -`PUT _ilm/policy/` +`PUT _ilm/policy/` ==== Description -This API creates a new Lifecycle Policy, or updates an existing one with the same -identifier. Each call will replace the existing policy and increment the `version` -associated with the policy. +Creates a lifecycle policy. If the specified policy exists, the policy is +replaced and the policy version is incremented. -NOTE: The `version` is only for informational purposes. Only the latest version -of the policy is stored. +NOTE: Only the latest version of the policy is stored, you cannot revert to +previous versions. ==== Path Parameters @@ -28,17 +27,11 @@ of the policy is stored. ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - PUT operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-cluster-mgt-privilege.asciidoc[] ==== Examples @@ -71,7 +64,7 @@ PUT _ilm/policy/my_policy // CONSOLE // TEST -If the request does not encounter errors, you receive the following result: +If the request succeeds, you receive the following result: [source,js] ---- { diff --git a/docs/reference/ilm/apis/remove-policy.asciidoc b/docs/reference/ilm/apis/remove-policy.asciidoc index f37ac9a715d..2811bc476e6 100644 --- a/docs/reference/ilm/apis/remove-policy.asciidoc +++ b/docs/reference/ilm/apis/remove-policy.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="basic"] -[[ilm-remove-policy]] -=== Remove Policy On Index API +[[ilm-delete-policy]] +=== Delete Policy from Index API ++++ -Remove Policy From Index +Delete Policy ++++ -Unassigns a policy from a specified index pattern +Removes the assigned lifecycle policy from an index. ==== Request @@ -14,8 +14,9 @@ Unassigns a policy from a specified index pattern ==== Description -This action removes a policy from managing an index. It is effectively the same as setting an index's -`index.lifecycle.name` setting to null. +Removes the assigned lifecycle policy and stops managing the specified index. +If an index pattern is specified, removes the assigned policies from all matching +indices. ==== Path Parameters @@ -24,21 +25,15 @@ This action removes a policy from managing an index. It is effectively the same ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-cluster-mgt-privilege.asciidoc[] ==== Examples -The following example removes a policy `my_policy` from an index `my_index`. +The following example removes the assigned policy from `my_index`. ////////////////////////// @@ -85,7 +80,7 @@ POST my_index/_ilm/remove // CONSOLE // TEST[continued] -If the request does not encounter errors, you receive the following result: +If the request succeeds, you receive the following result: [source,js] -------------------------------------------------- diff --git a/docs/reference/ilm/apis/retry-policy.asciidoc b/docs/reference/ilm/apis/retry-policy.asciidoc index 7c81f9423ef..51882c543e2 100644 --- a/docs/reference/ilm/apis/retry-policy.asciidoc +++ b/docs/reference/ilm/apis/retry-policy.asciidoc @@ -3,10 +3,10 @@ [[ilm-retry-policy]] === Retry Policy Execution API ++++ -Retry Policy Execution +Retry Policy ++++ -Retry executing the policy for an index which has errored. +Retry executing the policy for an index that is in the ERROR step. ==== Request @@ -14,10 +14,9 @@ Retry executing the policy for an index which has errored. ==== Description -This API will re-run a policy is currently in the ERROR step. It will set the -policy back to the step where the error occurred and attempt to re-execute it. -Information on whether an index is in the ERROR step can be obtained from the -<> +Sets the policy back to the step where the error occurred and executes the step. +Use the <> to determine if an index is in the ERROR +step. ==== Path Parameters @@ -26,21 +25,15 @@ Information on whether an index is in the ERROR step can be obtained from the ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - retry operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-index-mgt-privilege.asciidoc[] ==== Examples -The following example retries the policy for index `my_index`. +The following example retries the policy for `my_index`. [source,js] -------------------------------------------------- @@ -48,7 +41,7 @@ POST my_index/_ilm/retry -------------------------------------------------- // NOTCONSOLE -If the request does not encounter errors, you receive the following result: +If the request succeeds, you receive the following result: [source,js] -------------------------------------------------- diff --git a/docs/reference/ilm/apis/start.asciidoc b/docs/reference/ilm/apis/start.asciidoc index 073a584e4d8..6f2dffe9c33 100644 --- a/docs/reference/ilm/apis/start.asciidoc +++ b/docs/reference/ilm/apis/start.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="basic"] [[ilm-start]] -=== Start ILM API +=== Start {ILM} API ++++ -Start ILM +Start {ILM} ++++ -Start the ILM plugin +Start the {ILM} plugin. ==== Request @@ -14,23 +14,17 @@ Start the ILM plugin ==== Description -This API will start the ILM plugin if it is currently stopped. ILM is started -by default when the cluster is formed so this API is only needed if ILM has -been stopped using the <>. +Starts the {ILM} plugin if it is currently stopped. {ILM} is started +automatically when the cluster is formed. Restarting {ILM} is only +necessary if it has been stopped using the <>. ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the completion of the - start operation. When this period of time elapses, the API fails and returns - an error. The default value is `30s`. For more information about time units, - see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-cluster-mgt-privilege.asciidoc[] ==== Examples @@ -78,7 +72,7 @@ POST _ilm/start // CONSOLE // TEST[continued] -If the request does not encounter errors, you receive the following result: +If the request succeeds, you receive the following result: [source,js] -------------------------------------------------- diff --git a/docs/reference/ilm/apis/stop.asciidoc b/docs/reference/ilm/apis/stop.asciidoc index cdc038adabc..f1ffbc09c44 100644 --- a/docs/reference/ilm/apis/stop.asciidoc +++ b/docs/reference/ilm/apis/stop.asciidoc @@ -1,12 +1,12 @@ [role="xpack"] [testenv="basic"] [[ilm-stop]] -=== Stop ILM API +=== Stop {ILM} API ++++ -Stop ILM +Stop {ILM} ++++ -Stop the ILM plugin. +Stop the {ILM} plugin. ==== Request @@ -14,25 +14,22 @@ Stop the ILM plugin. ==== Description -This API will stop the ILM plugin. This can be used for period where -maintenance is required and ILM should not perform any actions on any indices. -The API will return as soon as the stop request has been acknowledged but the -plugin may not immediately stop but rather need to wait for some operations -to finish before it's stopped. Progress can be seen using the -<> API. +Halts all lifecycle management operations and stops the {ILM} plugin. This is +useful when you are performing maintenance on the cluster and need to prevent +{ILM} from performing any actions on your indices. + +The API returns as soon as the stop request has been acknowledged, but the +plugin might continue to run until in-progress operations complete and the plugin +can be safely stopped. Use the <> API to see +if {ILM} is running. ==== Request Parameters -`timeout`:: - (time units) Specifies the period of time to wait for the response. When this - period of time elapses, the API fails and returns an error. The default value - is `30s`. For more information about time units, see <>. +include::{docdir}/rest-api/timeoutparms.asciidoc[] -`master_timeout`:: - (time units) Specifies the period of time to wait for the connection with master. - When this period of time elapses, the API fails and returns an error. - The default value is `30s`. For more information about time units, see <>. +==== Authorization +include::ilm-cluster-mgt-privilege.asciidoc[] ==== Examples diff --git a/docs/reference/ilm/index.asciidoc b/docs/reference/ilm/index.asciidoc index d85f92fb1c2..be966895556 100644 --- a/docs/reference/ilm/index.asciidoc +++ b/docs/reference/ilm/index.asciidoc @@ -1,13 +1,14 @@ [role="xpack"] [testenv="basic"] [[index-lifecycle-management]] -= Managing Indices += Managing the index lifecycle :ilm: index lifecycle management -:ILM: Index lifecycle management +:Ilm: Index lifecycle management +:ILM: ILM [partintro] -- -The <> enable you to automate how you +The <> enable you to automate how you want to manage your indices over time. Rather than simply performing management actions on your indices on a set schedule, you can base actions on other factors such as shard size and performance requirements. diff --git a/docs/reference/ilm/update-lifecycle-policy.asciidoc b/docs/reference/ilm/update-lifecycle-policy.asciidoc index 334b5a953fd..97a3131241e 100644 --- a/docs/reference/ilm/update-lifecycle-policy.asciidoc +++ b/docs/reference/ilm/update-lifecycle-policy.asciidoc @@ -1,9 +1,12 @@ [role="xpack"] [testenv="basic"] [[update-lifecycle-policy]] -== Update lifecycle policy +== Update Lifecycle Policy +++++ +Update Policy +++++ -Updating existing ILM policies is useful to fix mistakes or change +You can update an existing lifecycle policy to fix mistakes or change strategies for newly created indices. It is possible to update policy definitions and an index's `index.lifecycle.name` settings independently. To prevent the situation that phase definitions are modified while currently being executed on an index, each index @@ -173,7 +176,7 @@ PUT my_index // TEST[continued] //// -The <> is useful to introspect managed indices to see which phase definition they are currently executing. +The <> is useful to introspect managed indices to see which phase definition they are currently executing. Using this API, we can find out that `my_index` is currently attempting to be rolled over. [source,js] diff --git a/docs/reference/rest-api/timeoutparms.asciidoc b/docs/reference/rest-api/timeoutparms.asciidoc new file mode 100644 index 00000000000..fc8f5208219 --- /dev/null +++ b/docs/reference/rest-api/timeoutparms.asciidoc @@ -0,0 +1,11 @@ +`timeout`:: + (time units) Specifies the period of time to wait for a response. If no + response is received before the timeout expires, the request fails and + returns an error. Defaults to `30s`. For more information about + time units, see <>. + +`master_timeout`:: + (time units) Specifies the period of time to wait for a connection to the + master node. If no response is received before the timeout expires, the request + fails and returns an error. Defaults to `30s`. For more information about + time units, see <>.