ISM API

Use the index state management operations to programmatically work with policies and managed indexes.

Create policy

Introduced 1.0

Creates a policy.

Example request

  1. PUT _plugins/_ism/policies/policy_1
  2. {
  3.   "policy": {
  4.     "description": "ingesting logs",
  5.     "default_state": "ingest",
  6.     "states": [
  7.       {
  8.         "name": "ingest",
  9.         "actions": [
  10.           {
  11.             "rollover": {
  12.               "min_doc_count": 5
  13.             }
  14.           }
  15.         ],
  16.         "transitions": [
  17.           {
  18.             "state_name": "search"
  19.           }
  20.         ]
  21.       },
  22.       {
  23.         "name": "search",
  24.         "actions": [],
  25.         "transitions": [
  26.           {
  27.             "state_name": "delete",
  28.             "conditions": {
  29.               "min_index_age": "5m"
  30.             }
  31.           }
  32.         ]
  33.       },
  34.       {
  35.         "name": "delete",
  36.         "actions": [
  37.           {
  38.             "delete": {}
  39.           }
  40.         ],
  41.         "transitions": []
  42.       }
  43.     ]
  44.   }
  45. }

Example response

  1. {
  2.   "_id": "policy_1",
  3.   "_version": 1,
  4.   "_primary_term": 1,
  5.   "_seq_no": 7,
  6.   "policy": {
  7.     "policy": {
  8.       "policy_id": "policy_1",
  9.       "description": "ingesting logs",
  10.       "last_updated_time": 1577990761311,
  11.       "schema_version": 1,
  12.       "error_notification": null,
  13.       "default_state": "ingest",
  14.       "states": [
  15.         {
  16.           "name": "ingest",
  17.           "actions": [
  18.             {
  19.               "rollover": {
  20.                 "min_doc_count": 5
  21.               }
  22.             }
  23.           ],
  24.           "transitions": [
  25.             {
  26.               "state_name": "search"
  27.             }
  28.           ]
  29.         },
  30.         {
  31.           "name": "search",
  32.           "actions": [],
  33.           "transitions": [
  34.             {
  35.               "state_name": "delete",
  36.               "conditions": {
  37.                 "min_index_age": "5m"
  38.               }
  39.             }
  40.           ]
  41.         },
  42.         {
  43.           "name": "delete",
  44.           "actions": [
  45.             {
  46.               "delete": {}
  47.             }
  48.           ],
  49.           "transitions": []
  50.         }
  51.       ]
  52.     }
  53.   }
  54. }

Add policy

Introduced 1.0

Adds a policy to an index. This operation does not change the policy if the index already has one.

Example request

  1. POST _plugins/_ism/add/index_1
  2. {
  3.   "policy_id": "policy_1"
  4. }

Example response

  1. {
  2.   "updated_indices": 1,
  3.   "failures": false,
  4.   "failed_indices": []
  5. }

If you use a wildcard * while adding a policy to an index, the ISM plugin interprets * as all indexes, including system indexes like .opendistro-security, which stores users, roles, and tenants. A delete action in your policy might accidentally delete all user roles and tenants in your cluster. Don’t use the broad * wildcard, and instead add a prefix, such as my-logs*, when specifying indexes with the _ism/add API.

Update policy

Introduced 1.0

Updates a policy. Use the seq_no and primary_term parameters to update an existing policy. If these numbers don’t match the existing policy or the policy doesn’t exist, ISM throws an error.

It’s possible that the policy currently applied to your index isn’t the most up-to-date policy available. To see what policy is currently applied to your index, see Explain index. To get the most up-to-date version of a policy, see Get policy.

Example request

  1. PUT _plugins/_ism/policies/policy_1?if_seq_no=7&if_primary_term=1
  2. {
  3.   "policy": {
  4.     "description": "ingesting logs",
  5.     "default_state": "ingest",
  6.     "states": [
  7.       {
  8.         "name": "ingest",
  9.         "actions": [
  10.           {
  11.             "rollover": {
  12.               "min_doc_count": 5
  13.             }
  14.           }
  15.         ],
  16.         "transitions": [
  17.           {
  18.             "state_name": "search"
  19.           }
  20.         ]
  21.       },
  22.       {
  23.         "name": "search",
  24.         "actions": [],
  25.         "transitions": [
  26.           {
  27.             "state_name": "delete",
  28.             "conditions": {
  29.               "min_index_age": "5m"
  30.             }
  31.           }
  32.         ]
  33.       },
  34.       {
  35.         "name": "delete",
  36.         "actions": [
  37.           {
  38.             "delete": {}
  39.           }
  40.         ],
  41.         "transitions": []
  42.       }
  43.     ]
  44.   }
  45. }

Example response

  1. {
  2.   "_id": "policy_1",
  3.   "_version": 2,
  4.   "_primary_term": 1,
  5.   "_seq_no": 10,
  6.   "policy": {
  7.     "policy": {
  8.       "policy_id": "policy_1",
  9.       "description": "ingesting logs",
  10.       "last_updated_time": 1577990934044,
  11.       "schema_version": 1,
  12.       "error_notification": null,
  13.       "default_state": "ingest",
  14.       "states": [
  15.         {
  16.           "name": "ingest",
  17.           "actions": [
  18.             {
  19.               "rollover": {
  20.                 "min_doc_count": 5
  21.               }
  22.             }
  23.           ],
  24.           "transitions": [
  25.             {
  26.               "state_name": "search"
  27.             }
  28.           ]
  29.         },
  30.         {
  31.           "name": "search",
  32.           "actions": [],
  33.           "transitions": [
  34.             {
  35.               "state_name": "delete",
  36.               "conditions": {
  37.                 "min_index_age": "5m"
  38.               }
  39.             }
  40.           ]
  41.         },
  42.         {
  43.           "name": "delete",
  44.           "actions": [
  45.             {
  46.               "delete": {}
  47.             }
  48.           ],
  49.           "transitions": []
  50.         }
  51.       ]
  52.     }
  53.   }
  54. }

Get policy

Introduced 1.0

Gets the policy by policy_id.

Example request

  1. GET _plugins/_ism/policies/policy_1

Example response

  1. {
  2.   "_id": "policy_1",
  3.   "_version": 2,
  4.   "_seq_no": 10,
  5.   "_primary_term": 1,
  6.   "policy": {
  7.     "policy_id": "policy_1",
  8.     "description": "ingesting logs",
  9.     "last_updated_time": 1577990934044,
  10.     "schema_version": 1,
  11.     "error_notification": null,
  12.     "default_state": "ingest",
  13.     "states": [
  14.       {
  15.         "name": "ingest",
  16.         "actions": [
  17.           {
  18.             "rollover": {
  19.               "min_doc_count": 5
  20.             }
  21.           }
  22.         ],
  23.         "transitions": [
  24.           {
  25.             "state_name": "search"
  26.           }
  27.         ]
  28.       },
  29.       {
  30.         "name": "search",
  31.         "actions": [],
  32.         "transitions": [
  33.           {
  34.             "state_name": "delete",
  35.             "conditions": {
  36.               "min_index_age": "5m"
  37.             }
  38.           }
  39.         ]
  40.       },
  41.       {
  42.         "name": "delete",
  43.         "actions": [
  44.           {
  45.             "delete": {}
  46.           }
  47.         ],
  48.         "transitions": []
  49.       }
  50.     ]
  51.   }
  52. }

Remove policy from index

Introduced 1.0

Removes any ISM policy from the index.

Example request

  1. POST _plugins/_ism/remove/index_1

Example response

  1. {
  2.   "updated_indices": 1,
  3.   "failures": false,
  4.   "failed_indices": []
  5. }

Update managed index policy

Introduced 1.0

Updates the managed index policy to a new policy (or to a new version of the policy). You can use an index pattern to update multiple indexes at once. When updating multiple indexes, you might want to include a state filter to only affect certain managed indexes. The change policy filters out all the existing managed indexes and only applies the change to the ones in the state that you specify. You can also explicitly specify the state that the managed index transitions to after the change policy takes effect.

A policy change is an asynchronous background process. The changes are queued and are not executed immediately by the background process. This delay in execution protects the currently running managed indexes from being put into a broken state. If the policy you are changing to has only some small configuration changes, then the change takes place immediately. For example, if the policy changes the min_index_age parameter in a rollover condition from 1000d to 100d, this change takes place immediately in its next execution. If the change modifies the state, actions, or the order of actions of the current state the index is in, then the change happens at the end of its current state before transitioning to a new state.

In this example, the policy applied on the index_1 index is changed to policy_1, which could either be a completely new policy or an updated version of its existing policy. The process only applies the change if the index is currently in the searches state. After this change in policy takes place, index_1 transitions to the delete state.

Example request

  1. POST _plugins/_ism/change_policy/index_1
  2. {
  3.   "policy_id": "policy_1",
  4.   "state": "delete",
  5.   "include": [
  6.     {
  7.       "state": "searches"
  8.     }
  9.   ]
  10. }

Example response

  1. {
  2.   "updated_indices": 0,
  3.   "failures": false,
  4.   "failed_indices": []
  5. }

Retry failed index

Introduced 1.0

Retries the failed action for an index. For the retry call to succeed, ISM must manage the index, and the index must be in a failed state. You can use index patterns (*) to retry multiple failed indexes.

Example request

  1. POST _plugins/_ism/retry/index_1
  2. {
  3.   "state": "delete"
  4. }

Example response

  1. {
  2.   "updated_indices": 0,
  3.   "failures": false,
  4.   "failed_indices": []
  5. }

Explain index

Introduced 1.0

Gets the current state of the index. You can use index patterns to get the status of multiple indexes.

Example request

  1. GET _plugins/_ism/explain/index_1

Example response

  1. {
  2.   "index_1": {
  3.     "index.plugins.index_state_management.policy_id": "policy_1"
  4.   }
  5. }

Optionally, you can add the show_policy parameter to your request’s path to get the policy that is currently applied to your index, which is useful for seeing whether the policy applied to your index is the latest one. To get the most up-to-date policy, see Get Policy API.

Example request

  1. GET _plugins/_ism/explain/index_1?show_policy=true

Example response

  1. {
  2.   "index_1": {
  3.     "index.plugins.index_state_management.policy_id": "sample-policy",
  4.     "index.opendistro.index_state_management.policy_id": "sample-policy",
  5.     "index": "index_1",
  6.     "index_uuid": "gCFlS_zcTdih8xyxf3jQ-A",
  7.     "policy_id": "sample-policy",
  8.     "enabled": true,
  9.     "policy": {
  10.       "policy_id": "sample-policy",
  11.       "description": "ingesting logs",
  12.       "last_updated_time": 1647284980148,
  13.       "schema_version": 13,
  14.       "error_notification": null,
  15.       "default_state": "ingest",
  16.       "states": [...],
  17.       "ism_template": null
  18.     }
  19.   },
  20.   "total_managed_indices": 1
  21. }

The plugins.index_state_management.policy_id setting is deprecated starting from ODFE version 1.13.0. We retain this field in the response API for consistency.

Delete policy

Introduced 1.0

Deletes the policy by policy_id.

Example request

  1. DELETE _plugins/_ism/policies/policy_1

Example response

  1. {
  2.   "_index": ".opendistro-ism-config",
  3.   "_id": "policy_1",
  4.   "_version": 3,
  5.   "result": "deleted",
  6.   "forced_refresh": true,
  7.   "_shards": {
  8.     "total": 2,
  9.     "successful": 2,
  10.     "failed": 0
  11.   },
  12.   "_seq_no": 15,
  13.   "_primary_term": 1
  14. }

Error prevention validation

Introduced 2.4

ISM allows you to run an action automatically. However, running an action can fail for a variety of reasons. You can use error prevention validation to test an action in order to rule out failures.

To enable error prevention validation, set the plugins.index_state_management.validation_service.enabled setting to true:

  1. PUT _cluster/settings
  2. {
  3.    "persistent":{
  4.       "plugins.index_state_management.validation_action.enabled": true
  5.    }
  6. }

Example response

  1. {
  2.   "acknowledged" : true,
  3.   "persistent" : {
  4.     "plugins" : {
  5.       "index_state_management" : {
  6.         "validation_action" : {
  7.           "enabled" : "true"
  8.         }
  9.       }
  10.     }
  11.   },
  12.   "transient" : { }
  13. }

To check an error prevention validation status and message, pass validate_action=true to the _plugins/_ism/explain endpoint:

  1. GET _plugins/_ism/explain/test-000001?validate_action=true

Example response

The response contains an additional validate object with a validation message and status:

  1. {
  2.   "test-000001" : {
  3.     "index.plugins.index_state_management.policy_id" : "test_rollover",
  4.     "index.opendistro.index_state_management.policy_id" : "test_rollover",
  5.     "index" : "test-000001",
  6.     "index_uuid" : "CgKsxFmQSIa8dWqpbSJmyA",
  7.     "policy_id" : "test_rollover",
  8.     "policy_seq_no" : -2,
  9.     "policy_primary_term" : 0,
  10.     "rolled_over" : false,
  11.     "index_creation_date" : 1667410460649,
  12.     "state" : {
  13.       "name" : "rollover",
  14.       "start_time" : 1667410766045
  15.     },
  16.     "action" : {
  17.       "name" : "rollover",
  18.       "start_time" : 1667411127803,
  19.       "index" : 0,
  20.       "failed" : false,
  21.       "consumed_retries" : 0,
  22.       "last_retry_time" : 0
  23.     },
  24.     "step" : {
  25.       "name" : "attempt_rollover",
  26.       "start_time" : 1667411127803,
  27.       "step_status" : "starting"
  28.     },
  29.     "retry_info" : {
  30.       "failed" : true,
  31.       "consumed_retries" : 0
  32.     },
  33.     "info" : {
  34.       "message" : "Previous action was not able to update IndexMetaData."
  35.     },
  36.     "enabled" : false,
  37.     "validate" : {
  38.       "validation_message" : "Missing rollover_alias index setting [index=test-000001]",
  39.       "validation_status" : "re_validating"
  40.     }
  41.   },
  42.   "total_managed_indices" : 1
  43. }

If you pass validate_action=false or do not pass a validate_action value to the _plugins/_ism/explain endpoint, the response will not contain an error prevention validation status and message:

  1. GET _plugins/_ism/explain/test-000001?validate_action=false

Or:

  1. GET _plugins/_ism/explain/test-000001

Example response

  1. {
  2.   "test-000001" : {
  3.     "index.plugins.index_state_management.policy_id" : "test_rollover",
  4.     "index.opendistro.index_state_management.policy_id" : "test_rollover",
  5.     "index" : "test-000001",
  6.     "index_uuid" : "CgKsxFmQSIa8dWqpbSJmyA",
  7.     "policy_id" : "test_rollover",
  8.     "policy_seq_no" : -2,
  9.     "policy_primary_term" : 0,
  10.     "rolled_over" : false,
  11.     "index_creation_date" : 1667410460649,
  12.     "state" : {
  13.       "name" : "rollover",
  14.       "start_time" : 1667410766045
  15.     },
  16.     "action" : {
  17.       "name" : "rollover",
  18.       "start_time" : 1667411127803,
  19.       "index" : 0,
  20.       "failed" : false,
  21.       "consumed_retries" : 0,
  22.       "last_retry_time" : 0
  23.     },
  24.     "step" : {
  25.       "name" : "attempt_rollover",
  26.       "start_time" : 1667411127803,
  27.       "step_status" : "starting"
  28.     },
  29.     "retry_info" : {
  30.       "failed" : true,
  31.       "consumed_retries" : 0
  32.     },
  33.     "info" : {
  34.       "message" : "Previous action was not able to update IndexMetaData."
  35.     },
  36.     "enabled" : false
  37.   },
  38.   "total_managed_indices" : 1
  39. }