ISM API
Use the index state management operations to programmatically work with policies and managed indices.
Table of contents
- Add policy at index creation
- Create policy
- Add policy
- Update policy
- Get policy
- Remove policy from index
- Update managed index policy
- Retry failed index
- Explain index
- Delete policy
Add policy at index creation
You can attach a policy to an index at the time you’re creating the index.
Request
PUT index_1
{
"settings": {
"opendistro.index_state_management.policy_id": "ingest_policy",
"opendistro.index_state_management.rollover_alias": "some_alias"
},
"aliases": {
"some_alias": {
"is_write_index": true
}
}
}
In this case, the ingest_policy is applied to index_1 with the rollover action defined in some_alias.
Create policy
Creates a policy.
Request
PUT _opendistro/_ism/policies/policy_1
{
"policy": {
"description": "ingesting logs",
"default_state": "ingest",
"states": [
{
"name": "ingest",
"actions": [
{
"rollover": {
"min_doc_count": 5
}
}
],
"transitions": [
{
"state_name": "search"
}
]
},
{
"name": "search",
"actions": [],
"transitions": [
{
"state_name": "delete",
"conditions": {
"min_index_age": "5m"
}
}
]
},
{
"name": "delete",
"actions": [
{
"delete": {}
}
],
"transitions": []
}
]
}
}
Sample response
{
"_id": "policy_1",
"_version": 1,
"_primary_term": 1,
"_seq_no": 7,
"policy": {
"policy": {
"policy_id": "policy_1",
"description": "ingesting logs",
"last_updated_time": 1577990761311,
"schema_version": 1,
"error_notification": null,
"default_state": "ingest",
"states": [
{
"name": "ingest",
"actions": [
{
"rollover": {
"min_doc_count": 5
}
}
],
"transitions": [
{
"state_name": "search"
}
]
},
{
"name": "search",
"actions": [],
"transitions": [
{
"state_name": "delete",
"conditions": {
"min_index_age": "5m"
}
}
]
},
{
"name": "delete",
"actions": [
{
"delete": {}
}
],
"transitions": []
}
]
}
}
}
Add policy
Adds a policy to an index. This operation does not change the policy if the index already has one.
Request
POST _opendistro/_ism/add/index_1
{
"policy_id": "policy_1"
}
Sample response
{
"updated_indices": 1,
"failures": false,
"failed_indices": []
}
Update policy
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.
Request
PUT _opendistro/_ism/policies/policy_1?if_seq_no=7&if_primary_term=1
{
"policy": {
"description": "ingesting logs",
"default_state": "ingest",
"states": [
{
"name": "ingest",
"actions": [
{
"rollover": {
"min_doc_count": 5
}
}
],
"transitions": [
{
"state_name": "search"
}
]
},
{
"name": "search",
"actions": [],
"transitions": [
{
"state_name": "delete",
"conditions": {
"min_index_age": "5m"
}
}
]
},
{
"name": "delete",
"actions": [
{
"delete": {}
}
],
"transitions": []
}
]
}
}
Sample response
{
"_id": "policy_1",
"_version": 2,
"_primary_term": 1,
"_seq_no": 10,
"policy": {
"policy": {
"policy_id": "policy_1",
"description": "ingesting logs",
"last_updated_time": 1577990934044,
"schema_version": 1,
"error_notification": null,
"default_state": "ingest",
"states": [
{
"name": "ingest",
"actions": [
{
"rollover": {
"min_doc_count": 5
}
}
],
"transitions": [
{
"state_name": "search"
}
]
},
{
"name": "search",
"actions": [],
"transitions": [
{
"state_name": "delete",
"conditions": {
"min_index_age": "5m"
}
}
]
},
{
"name": "delete",
"actions": [
{
"delete": {}
}
],
"transitions": []
}
]
}
}
}
Get policy
Gets the policy by policy_id.
Request
GET _opendistro/_ism/policies/policy_1
Sample response
{
"_id": "policy_1",
"_version": 2,
"_seq_no": 10,
"_primary_term": 1,
"policy": {
"policy_id": "policy_1",
"description": "ingesting logs",
"last_updated_time": 1577990934044,
"schema_version": 1,
"error_notification": null,
"default_state": "ingest",
"states": [
{
"name": "ingest",
"actions": [
{
"rollover": {
"min_doc_count": 5
}
}
],
"transitions": [
{
"state_name": "search"
}
]
},
{
"name": "search",
"actions": [],
"transitions": [
{
"state_name": "delete",
"conditions": {
"min_index_age": "5m"
}
}
]
},
{
"name": "delete",
"actions": [
{
"delete": {}
}
],
"transitions": []
}
]
}
}
Remove policy from index
Removes any ISM policy from the index.
Request
POST _opendistro/_ism/remove/index_1
Sample response
{
"updated_indices": 1,
"failures": false,
"failed_indices": []
}
Update managed index policy
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 indices at once. When updating multiple indices, you might want to include a state filter to only affect certain managed indices.
Request
POST _opendistro/_ism/change_policy/index_1
{
"policy_id": "policy_1",
"state": "delete",
"include": [
{
"state": "searches"
}
]
}
Sample response
{
"updated_indices": 0,
"failures": false,
"failed_indices": []
}
Retry failed index
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 indices.
Request
POST _opendistro/_ism/retry/index_1
{
"state": "delete"
}
Sample response
{
"updated_indices": 0,
"failures": false,
"failed_indices": []
}
Explain index
Gets the current state of the index. You can use index patterns to get the status of multiple indices.
Request
GET _opendistro/_ism/explain/index_1
Sample response
{
"index_1": {
"index.opendistro.index_state_management.policy_id": "policy_1"
}
}
Delete policy
Deletes the policy by policy_id.
Request
DELETE _opendistro/_ism/policies/policy_1
Sample response
{
"_index": ".opendistro-ism-config",
"_type": "_doc",
"_id": "policy_1",
"_version": 3,
"result": "deleted",
"forced_refresh": true,
"_shards": {
"total": 2,
"successful": 2,
"failed": 0
},
"_seq_no": 15,
"_primary_term": 1
}