honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

initial api reference docs for ILM (#33866) 

This adds the bulk of the ILM APIs in docs with examples
This commit is contained in:
Tal Levy 2018-10-16 12:18:54 -07:00 committed by GitHub
parent 80474e138f
commit 2846effc74
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 1312 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
x-pack/docs/en/ilm/apis/delete-lifecycle.asciidoc Normal file
View File

@ -0,0 +1,89 @@
[role="xpack"]
[testenv="basic"]
[[ilm-delete-lifecycle]]
=== Delete Lifecycle Policy API
++++
<titleabbrev>Delete Policy</titleabbrev>
++++
Deletes an existing lifecycle policy
==== Request
`DELETE _ilm/<policy>`
==== Description
Deletes an existing lifecycle policy
==== Path Parameters
`policy` (required)::
(string) Identifier for the 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example deletes an existing policy named `my_policy`:
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
DELETE _ilm/my_policy
--------------------------------------------------
// CONSOLE
// TEST[continued]
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"acknowledged": true
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE

289
x-pack/docs/en/ilm/apis/explain.asciidoc Normal file
View File

@ -0,0 +1,289 @@
[role="xpack"]
[testenv="basic"]
[[ilm-explain]]
=== Explain Lifecycle API
++++
<titleabbrev>Explain Lifecycle</titleabbrev>
++++
Shows the current lifecycle status for an index.
==== Request
`GET <index>/_ilm/explain`
==== 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.
==== Path Parameters
`index` (required)::
(string) Identifier for the index.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example retrieves the lifecycle state for the index `my_index`:
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
PUT my_index
{
"settings": {
"index.lifecycle.name": "my_policy",
"index.number_of_replicas": 0
}
}
GET /_cluster/health?wait_for_status=green&timeout=10s
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
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:
[source,js]
--------------------------------------------------
{
"indices": {
"my_index": {
"index": "my_index",
"managed": true, <1>
"policy": "my_policy", <2>
"skip": false, <3>
"lifecycle_date": 1538475653281, <4>
"phase": "new", <5>
"phase_time": 1538475653317, <6>
"action": "complete", <7>
"action_time": 1538475653317, <8>
"step": "complete", <9>
"step_time": 1538475653317 <10>
}
}
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE[s/"lifecycle_date": 1538475653281/"lifecycle_date": $body.indices.my_index.lifecycle_date/]
// TESTRESPONSE[s/"phase_time": 1538475653317/"phase_time": null/]
// TESTRESPONSE[s/"action_time": 1538475653317/"action_time": $body.indices.my_index.action_time/]
// TESTRESPONSE[s/"step_time": 1538475653317/"step_time": $body.indices.my_index.step_time/]
<1> Shows if the index is being managed by ILM. If the index is not managed by
ILM the other fields will not be shown
<2> The name of the policy which ILM is using for this index
<3> Shows whether ILM execution for the index is currently set to be skipped
<4> The timestamp used for the `minimum_age`
<5> The current phase
<6> The timestamp for when the index entered the current phase
<7> The current action
<8> The timestamp for when the index entered the current action
<9> The current step
<10> The timestamp for 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.
Changes to the underlying policy will not affect this index until the current
phase definition has been completely executed.
[source,js]
--------------------------------------------------
{
"indices": {
"test-000069": {
"index": "test-000069",
"managed": true,
"policy": "my_lifecycle3",
"skip": false,
"lifecycle_date": "2018-10-15T13:45:21.981Z",
"phase": "hot",
"phase_time": "2018-10-15T13:45:22.577Z",
"action": "rollover",
"action_time": "2018-10-15T13:45:22.577Z",
"step": "attempt_rollover",
"step_time": "2018-10-15T13:45:22.577Z",
"phase_execution": { <1>
"policy": "my_lifecycle3", <2>
"phase_definition": { <3>
"minimum_age": "0ms",
"actions": {
"rollover": {
"max_age": "30s"
}
}
},
"version": 3, <4>
"modified_date": "2018-10-15T13:21:41.576Z", <5>
"modified_date_in_millis": 1539609701576 <6>
}
}
}
}
--------------------------------------------------
// 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
If the policy is waiting for a step to complete for the index, the response will contain step information such as:
[source,js]
--------------------------------------------------
{
"indices": {
"test-000020": {
"index": "test-000020",
"managed": true,
"policy": "my_lifecycle3",
"skip": false,
"lifecycle_date": "2018-10-15T13:20:28.042Z",
"phase": "warm",
"phase_time": "2018-10-15T13:20:28.428Z",
"action": "allocate",
"action_time": "2018-10-15T13:20:28.428Z",
"step": "check-allocation",
"step_time": "2018-10-15T13:20:28.633Z",
"step_info": { <1>
"message": "Waiting for all shard copies to be active",
"shards_left_to_allocate": -1,
"all_shards_active": false,
"actual_replicas": 2
},
"phase_execution": {
"policy": "my_lifecycle3",
"phase_definition": {
"minimum_age": "0ms",
"actions": {
"allocate": {
"number_of_replicas": 2,
"include": {
"box_type": "warm"
},
"exclude": {},
"require": {}
},
"forcemerge": {
"max_num_segments": 1
}
}
},
"version": 2,
"modified_date": "2018-10-15T13:20:02.489Z",
"modified_date_in_millis": 1539609602489
}
}
}
}
--------------------------------------------------
// 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.
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`.
[source,js]
--------------------------------------------------
{
"indices": {
"test-000056": {
"index": "test-000056",
"managed": true,
"policy": "my_lifecycle3",
"skip": false,
"lifecycle_date": "2018-10-15T13:38:26.209Z",
"phase": "hot",
"phase_time": "2018-10-15T13:38:26.706Z",
"action": "rollover",
"action_time": "2018-10-15T13:38:26.706Z",
"step": "ERROR",
"step_time": "2018-10-15T13:39:15.304Z",
"failed_step": "attempt_rollover", <1>
"step_info": { <2>
"type": "resource_already_exists_exception",
"reason": "index [test-000057/H7lF9n36Rzqa-KfKcnGQMg] already exists",
"index_uuid": "H7lF9n36Rzqa-KfKcnGQMg",
"index": "test-000057"
},
"phase_execution": {
"policy": "my_lifecycle3",
"phase_definition": {
"minimum_age": "0ms",
"actions": {
"rollover": {
"max_age": "30s"
}
}
},
"version": 3,
"modified_date": "2018-10-15T13:21:41.576Z",
"modified_date_in_millis": 1539609701576
}
}
}
}
--------------------------------------------------
// 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

115
x-pack/docs/en/ilm/apis/get-lifecycle.asciidoc Normal file
View File

@ -0,0 +1,115 @@
[role="xpack"]
[testenv="basic"]
[[ilm-get-lifecycle]]
=== Get Lifecycle Policy API
++++
<titleabbrev>Get Policy</titleabbrev>
++++
Retrieves an existing policy
==== Request
`GET _ilm`
`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.
==== Path Parameters
`policy` (optional)::
(string) Identifier for the policy.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example retrieves the policy named `my_policy`:
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
GET _ilm
--------------------------------------------------
// CONSOLE
// TEST[continued]
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"my_policy": {
"version": 1, <1>
"modified_date": 82392349, <2>
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
}
--------------------------------------------------
// 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

56
x-pack/docs/en/ilm/apis/get-status.asciidoc Normal file
View File

@ -0,0 +1,56 @@
[role="xpack"]
[testenv="basic"]
[[ilm-get-status]]
=== Get ILM Status API
++++
<titleabbrev>Get ILM Status</titleabbrev>
++++
Gets the current status for ILM.
==== Request
`POST /_ilm/status`
==== 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 <<ilm-start, Start ILM>>
and <<ilm-stop, Stop ILM>> 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example stops the ILM plugin.
[source,js]
--------------------------------------------------
GET _ilm/status
--------------------------------------------------
// CONSOLE
// TEST
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"operation_mode": "RUNNING"
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE

44
x-pack/docs/en/ilm/apis/ilm-api.asciidoc Normal file
View File

@ -0,0 +1,44 @@
[[index-lifecycle-management-api]]
== Index Lifecycle Management API
You can use the following APIs to manage policies on indices.
[float]
[[ilm-api-policy-endpoint]]
=== Policy Management APIs
* <<ilm-put-lifecycle,Create Lifecycle Policy>>
* <<ilm-get-lifecycle,Get Lifecycle Policy>>
* <<ilm-delete-lifecycle,Delete Lifecycle Policy>>
[float]
[[ilm-api-index-endpoint]]
=== Index Management APIs
* <<ilm-move-to-step,Move Index To Step>>
* <<ilm-set-policy,Set Policy On Index>>
* <<ilm-retry-policy,Retry Policy On Indices>>
[float]
[[ilm-api-management-endpoint]]
=== Operation Management APIs
* <<ilm-get-status,Get ILM Operation Mode>>
* <<ilm-start,Start ILM>>
* <<ilm-stop,Stop ILM>>
* <<ilm-explain,Explain API>>
include::put-lifecycle.asciidoc[]
include::get-lifecycle.asciidoc[]
include::delete-lifecycle.asciidoc[]
include::move-to-step.asciidoc[]
include::set-policy.asciidoc[]
include::remove-policy.asciidoc[]
include::retry-policy.asciidoc[]
include::get-status.asciidoc[]
include::explain.asciidoc[]
include::start.asciidoc[]
include::stop.asciidoc[]

121
x-pack/docs/en/ilm/apis/move-to-step.asciidoc Normal file
View File

@ -0,0 +1,121 @@
[role="xpack"]
[testenv="basic"]
[[ilm-move-to-step]]
=== Move To Step API
++++
<titleabbrev>Move To Step</titleabbrev>
++++
Moves a managed index into a specific execution step its policy
==== Request
`POST _ilm/move/<index>`
==== 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.
This API changes the current step for the specified index to the step supplied in the body of the request
==== Path Parameters
`index` (required)::
(string) Identifier for the index.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example moves the index `my_index` from the initial step to the
forcemerge step:
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
PUT my_index
{
"settings": {
"index.lifecycle.name": "my_policy"
}
}
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
POST _ilm/move/my_index
{
"current_step": { <1>
"phase": "new",
"action": "complete",
"name": "complete"
},
"next_step": { <2>
"phase": "warm",
"action": "forcemerge",
"name": "forcemerge"
}
}
--------------------------------------------------
// 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
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"acknowledged": true
}
--------------------------------------------------
// 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`.

82
x-pack/docs/en/ilm/apis/put-lifecycle.asciidoc Normal file
View File

@ -0,0 +1,82 @@
[role="xpack"]
[testenv="basic"]
[[ilm-put-lifecycle]]
=== Put Lifecycle Policy API
++++
<titleabbrev>Put Policy</titleabbrev>
++++
Creates or updates an ILM Policy
==== Request
`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.
NOTE: The `version` is only for informational purposes. Only the latest version
of the policy is stored.
==== Path Parameters
`policy` (required)::
(string) Identifier for the policy.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example creates a new policy named `my_policy`:
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
--------------------------------------------------
// CONSOLE
// TEST
If the request does not encounter errors, you receive the following result:
[source,js]
----
{
"acknowledged": true
}
----
// CONSOLE
// TESTRESPONSE

95
x-pack/docs/en/ilm/apis/remove-policy.asciidoc Normal file
View File

@ -0,0 +1,95 @@
[role="xpack"]
[testenv="basic"]
[[ilm-remove-policy]]
=== Remove Policy On Index API
++++
<titleabbrev>Remove Policy From Index</titleabbrev>
++++
Unassigns a policy from a specified index pattern
==== Request
`DELETE <index>/_ilm`
==== 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.
==== Path Parameters
`index` (required)::
(string) Identifier for the index.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example removes a policy `my_policy` from an index `my_index`.
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
PUT my_index
PUT my_index/_ilm/my_policy
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
DELETE my_index/_ilm
--------------------------------------------------
// CONSOLE
// TEST[continued]
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"has_failures" : false,
"failed_indexes" : []
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE

59
x-pack/docs/en/ilm/apis/retry-policy.asciidoc Normal file
View File

@ -0,0 +1,59 @@
[role="xpack"]
[testenv="basic"]
[[ilm-retry-policy]]
=== Retry Policy Execution API
++++
<titleabbrev>Retry Policy Execution</titleabbrev>
++++
Retry executing the policy for an index which has errored.
==== Request
`POST <index>/_ilm/retry`
==== 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
<<ilm-explain, ILM Explain API>>
==== Path Parameters
`index` (required)::
(string) Identifier for the indices to retry in comma-separated format.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example retries the policy for index `my_index`.
[source,js]
--------------------------------------------------
POST my_index/_ilm/retry
--------------------------------------------------
// NOTCONSOLE
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"acknowledged": true
}
--------------------------------------------------
// NOTCONSOLE

96
x-pack/docs/en/ilm/apis/set-policy.asciidoc Normal file
View File

@ -0,0 +1,96 @@
[role="xpack"]
[testenv="basic"]
[[ilm-set-policy]]
=== Set Policy On Index API
++++
<titleabbrev>Set Policy On Index</titleabbrev>
++++
Assigns a policy to an index for management.
==== Request
`POST <index>/_ilm/<policy>`
==== Description
This action assigns a policy to an index. It is effectively the same as setting an index's
`index.lifecycle.name` setting.
==== Path Parameters
`index` (required)::
(string) Identifier for the index.
`policy` (required)::
(string) Identifier for the policy.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example assigns a policy `my_policy` to an index `my_index`.
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
PUT my_index
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
PUT my_index/_ilm/my_policy
--------------------------------------------------
// CONSOLE
// TEST[continued]
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"has_failures" : false,
"failed_indexes" : []
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE

90
x-pack/docs/en/ilm/apis/start.asciidoc Normal file
View File

@ -0,0 +1,90 @@
[role="xpack"]
[testenv="basic"]
[[ilm-start]]
=== Start ILM API
++++
<titleabbrev>Start ILM</titleabbrev>
++++
Start the ILM plugin
==== Request
`POST /_ilm/start`
==== 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 <<ilm-stop, Stop ILM API>>.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example starts the ILM plugin.
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
PUT my_index
POST _ilm/stop
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
POST _ilm/start
--------------------------------------------------
// CONSOLE
// TEST[continued]
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"acknowledged": true
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE

90
x-pack/docs/en/ilm/apis/stop.asciidoc Normal file
View File

@ -0,0 +1,90 @@
[role="xpack"]
[testenv="basic"]
[[ilm-stop]]
=== Stop ILM API
++++
<titleabbrev>Stop ILM</titleabbrev>
++++
Stop the ILM plugin.
==== Request
`POST /_ilm/stop`
==== 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
<<ilm-get-status, Get ILM Status>> API.
==== 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 <<time-units>>.
`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 <<time-units>>.
==== Examples
The following example stops the ILM plugin.
//////////////////////////
[source,js]
--------------------------------------------------
PUT _ilm/my_policy
{
"policy": {
"phases": {
"warm": {
"minimum_age": "10d",
"actions": {
"forcemerge": {
"max_num_segments": 1
}
}
},
"delete": {
"minimum_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}
PUT my_index
--------------------------------------------------
// CONSOLE
// TEST
//////////////////////////
[source,js]
--------------------------------------------------
POST _ilm/stop
--------------------------------------------------
// CONSOLE
// TEST[continued]
If the request does not encounter errors, you receive the following result:
[source,js]
--------------------------------------------------
{
"acknowledged": true
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE

4
x-pack/docs/en/ilm/ilm-api.asciidoc
View File

@ -1,4 +0,0 @@
[[index-lifecycle-management-api]]
== {ilm} API
TBD

16
x-pack/docs/en/ilm/index.asciidoc
View File

@ -47,23 +47,23 @@ hardware.
. Delete the index once the required 30 day retention period is reached.
--
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/index-lifecycle-management/getting-started-ilm.asciidoc
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/ilm/getting-started-ilm.asciidoc
include::getting-started-ilm.asciidoc[]
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/index-lifecycle-management/using-policies--rollover.asciidoc
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/ilm/using-policies--rollover.asciidoc
include::using-policies-rollover.asciidoc[]
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/index-lifecycle-management/set-up-policy.asciidoc
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/ilm/set-up-policy.asciidoc
include::set-up-lifecycle-policy.asciidoc[]
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/index-lifecycle-management/update-lifecycle-policy.asciidoc
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/ilm/update-lifecycle-policy.asciidoc
include::update-lifecycle-policy.asciidoc[]
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/index-lifecycle-management/get-index-lifecycle-information.asciidoc
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/ilm/get-index-lifecycle-information.asciidoc
include::get-index-lifecycle-information.asciidoc[]
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/index-lifecycle-management/pause-resume-ilm.asciidoc
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/ilm/pause-resume-ilm.asciidoc
include::pause-resume-ilm.asciidoc[]
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/index-lifecycle-management/getting-started-ilm.asciidoc
include::ilm-api.asciidoc[]
:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/ilm/apis/ilm-api.asciidoc
include::{xes-repo-dir}/ilm/apis/ilm-api.asciidoc[]

2
x-pack/docs/en/index-lifecycle/index.asciidoc
View File

@ -1,2 +0,0 @@
[[xpack-index-lifecycle]]
= Automating Index Properties Over Time

63
x-pack/plugin/core/src/test/java/org/elasticsearch/xpack/core/indexlifecycle/ILMRestTestStateCleaner.java Normal file
View File

@ -0,0 +1,63 @@
/*
* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
* or more contributor license agreements. Licensed under the Elastic License;
* you may not use this file except in compliance with the Elastic License.
*/
package org.elasticsearch.xpack.core.indexlifecycle;
import org.elasticsearch.client.Request;
import org.elasticsearch.client.Response;
import org.elasticsearch.client.RestClient;
import org.elasticsearch.test.rest.ESRestTestCase;
import java.io.IOException;
import java.util.Map;
public class ILMRestTestStateCleaner {
public static void clearILMMetadata(RestClient adminClient) throws Exception {
removePoliciesFromAllIndexes(adminClient);
deleteAllPolicies(adminClient);
// indices will be deleted by the ESRestTestCase class
}
private static void removePoliciesFromAllIndexes(RestClient adminClient) throws IOException {
Response response = adminClient.performRequest(new Request("GET", "/_all"));
Map<String, Object> indexes = ESRestTestCase.entityAsMap(response);
if (indexes == null || indexes.isEmpty()) {
return;
}
for (String indexName : indexes.keySet()) {
try {
adminClient.performRequest(new Request("DELETE", indexName + "/_ilm/"));
} catch (Exception e) {
// ok
}
}
}
private static void deleteAllPolicies(RestClient adminClient) throws Exception {
Map<String, Object> policies;
try {
Response response = adminClient.performRequest(new Request("GET", "/_ilm"));
policies = ESRestTestCase.entityAsMap(response);
} catch (Exception e) {
return;
}
if (policies == null || policies.isEmpty()) {
return;
}
for (String policyName : policies.keySet()) {
try {
adminClient.performRequest(new Request("DELETE", "/_ilm/" + policyName));
} catch (Exception e) {
// ok
}
}
}
}

15
x-pack/plugin/src/test/java/org/elasticsearch/xpack/test/rest/XPackRestIT.java
View File

@ -6,6 +6,7 @@
package org.elasticsearch.xpack.test.rest;
import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
import org.apache.http.HttpStatus;
import org.elasticsearch.ElasticsearchException;
import org.elasticsearch.client.Request;
@ -20,6 +21,7 @@ import org.elasticsearch.test.rest.yaml.ClientYamlTestCandidate;
import org.elasticsearch.test.rest.yaml.ClientYamlTestResponse;
import org.elasticsearch.test.rest.yaml.ESClientYamlSuiteTestCase;
import org.elasticsearch.test.rest.yaml.ObjectPath;
import org.elasticsearch.xpack.core.indexlifecycle.ILMRestTestStateCleaner;
import org.elasticsearch.xpack.core.ml.MlMetaIndex;
import org.elasticsearch.xpack.core.ml.integration.MlRestTestStateCleaner;
import org.elasticsearch.xpack.core.ml.job.persistence.AnomalyDetectorsIndex;
@ -244,6 +246,7 @@ public class XPackRestIT extends ESClientYamlSuiteTestCase {
disableMonitoring();
clearMlState();
clearRollupState();
clearILMState();
if (isWaitForPendingTasks()) {
// This waits for pending tasks to complete, so must go last (otherwise
// it could be waiting for pending tasks while monitoring is still running).
@ -271,6 +274,12 @@ public class XPackRestIT extends ESClientYamlSuiteTestCase {
}
}
private void clearILMState() throws Exception {
if (isILMTest()) {
ILMRestTestStateCleaner.clearILMMetadata(adminClient());
}
}
/**
* Executes an API call using the admin context, waiting for it to succeed.
*/
@ -336,6 +345,12 @@ public class XPackRestIT extends ESClientYamlSuiteTestCase {
return testName != null && (testName.contains("=rollup/") || testName.contains("=rollup\\"));
}
protected boolean isILMTest() {
String testName = getTestName();
return testName != null && (testName.contains("=ilm/") || testName.contains("=ilm\\"))
|| (testName.contains("/ilm/") || testName.contains("\\ilm\\"));
}
/**
* Should each test wait for pending tasks to finish after execution?
* @return Wait for pending tasks