ISM API
使用索引状态管理操作以编程方式处理策略和托管索引。
创建策略
创建策略。
示例请求
PUT _plugins/_ism/policies/policy_1
{
"policy": {
"description": "摄取日志",
"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": []
}
]
}
}
示例响应
{
"_id": "policy_1",
"_version": 1,
"_primary_term": 1,
"_seq_no": 7,
"policy": {
"policy": {
"policy_id": "policy_1",
"description": "摄取日志",
"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": []
}
]
}
}
}
添加策略
向索引添加策略。如果索引已有策略，此操作不会更改策略。
示例请求
POST _plugins/_ism/add/index_1
{
"policy_id": "policy_1"
}
示例响应
{
"updated_indices": 1,
"failures": false,
"failed_indices": []
}
如果你在向索引添加策略时使用通配符 *，ISM 插件会将 * 解释为所有索引，包括系统索引，如 .opendistro-security，它存储用户、角色和租户。策略中的删除操作可能会意外删除集群中的所有用户角色和租户。
不要使用宽泛的 * 通配符，而是添加前缀，如 my-logs*，在使用 _ism/add API 指定索引时。
更新策略
1.0 中引入
更新策略。使用 seq_no 和 primary_term 参数更新现有策略。如果这些数字与现有策略不匹配或策略不存在，ISM 会抛出错误。
当前应用于索引的策略可能不是最新的策略。要查看当前应用于索引的策略，请参见 解释索引。要获取策略的最新版本，请参见 获取策略。
示例请求
PUT _plugins/_ism/policies/policy_1?if_seq_no=7&if_primary_term=1
{
"policy": {
"description": "摄取日志",
"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": []
}
]
}
}
示例响应
{
"_id": "policy_1",
"_version": 2,
"_primary_term": 1,
"_seq_no": 10,
"policy": {
"policy": {
"policy_id": "policy_1",
"description": "摄取日志",
"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": []
}
]
}
}
}
获取策略
通过 policy_id 获取策略。
示例请求
GET _plugins/_ism/policies/policy_1
示例响应
{
"_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": []
}
]
}
}
从索引中移除策略
从索引中移除任何 ISM 策略。
示例请求
POST _plugins/_ism/remove/index_1
示例响应
{
"updated_indices": 1,
"failures": false,
"failed_indices": []
}
更新托管索引策略
将托管索引策略更新为新策略（或策略的新版本）。你可以使用索引模式一次更新多个索引。更新多个索引时，可能需要包含状态过滤器以仅影响某些托管索引。更改策略过滤器过滤掉所有现有托管索引，并仅将其应用于你指定的状态的索引。你还可以明确指定托管索引在更改策略生效后转换到的状态。
策略更改是异步后台过程。更改排队，并非由后台进程立即执行。执行中的这种延迟保护当前运行的托管索引免于被破坏。如果你更改的策略只有一些小的配置更改，则更改立即生效。例如，如果策略将 rollover 条件中的 min_index_age 参数从 1000d 更改为 100d，则此更改在其下一次执行中立即生效。如果更改修改了索引当前所在的状态、操作或操作顺序，则更改在其当前状态结束之前发生，然后转换到新状态。
在此示例中，应用于 index_1 索引的策略更改为 policy_1，这可能是全新的策略或其现有策略的更新版本。此过程仅在索引当前处于 searches 状态时应用更改。在此策略更改生效后，index_1 转换到 delete 状态。
示例请求
POST _plugins/_ism/change_policy/index_1
{
"policy_id": "policy_1",
"state": "delete",
"include": [
{
"state": "searches"
}
]
}
示例响应
{
"updated_indices": 0,
"failures": false,
"failed_indices": []
}
重试失败的索引
重试索引的失败操作。要使重试调用成功，ISM 必须管理索引，并且索引必须处于失败状态。你可以使用索引模式 (*) 重试多个失败索引。
示例请求
POST _plugins/_ism/retry/index_1
{
"state": "delete"
}
示例响应
{
"updated_indices": 0,
"failures": false,
"failed_indices": []
}
解释索引
获取索引的当前状态。你可以使用索引模式获取多个索引的状态。
示例请求
GET _plugins/_ism/explain/index_1
示例响应
{
"index_1": {
"index.plugins.index_state_management.policy_id": "policy_1"
}
}
你可以选择将 show_policy 参数添加到请求路径中，以获取当前应用于索引的策略，这对于查看索引应用的策略是否为最新策略很有用。要获取最新策略，请参见 获取策略 API。
示例请求
GET _plugins/_ism/explain/index_1?show_policy=true
示例响应
{
"index_1": {
"index.plugins.index_state_management.policy_id": "sample-policy",
"index.opendistro.index_state_management.policy_id": "sample-policy",
"index": "index_1",
"index_uuid": "gCFlS_zcTdih8xyxf3jQ-A",
"policy_id": "sample-policy",
"enabled": true,
"policy": {
"policy_id": "sample-policy",
"description": "ingesting logs",
"last_updated_time": 1647284980148,
"schema_version": 13,
"error_notification": null,
"default_state": "ingest",
"states": [...],
"ism_template": null
}
},
"total_managed_indices": 1
}
plugins.index_state_management.policy_id 设置从 ODFE 版本 1.13.0 开始已弃用。我们在响应 API 中保留此字段以保持一致性。
删除策略
1.0 中引入
通过 policy_id 删除策略。
示例请求
DELETE _plugins/_ism/policies/policy_1
示例响应
{
"_index": ".opendistro-ism-config",
"_id": "policy_1",
"_version": 3,
"result": "deleted",
"forced_refresh": true,
"_shards": {
"total": 2,
"successful": 2,
"failed": 0
},
"_seq_no": 15,
"_primary_term": 1
}
错误预防验证
2.4 中引入
ISM 允许你自动运行操作。但是，由于多种原因，运行操作可能会失败。你可以使用错误预防验证来测试操作，以排除故障。
要启用错误预防验证，请将 plugins.index_state_management.action_validation.enabled 设置设置为 true：
PUT _cluster/settings
{
"persistent":{
"plugins.index_state_management.action_validation.enabled": true
}
}
示例响应
{
"acknowledged" : true,
"persistent" : {
"plugins" : {
"index_state_management" : {
"validation_action" : {
"enabled" : "true"
}
}
}
},
"transient" : { }
}
要检查错误预防验证状态和消息，请将 validate_action=true 传递给 _plugins/_ism/explain 端点：
GET _plugins/_ism/explain/test-000001?validate_action=true
示例响应
响应包含一个额外的验证对象，其中包含验证消息和状态：
{
"test-000001" : {
"index.plugins.index_state_management.policy_id" : "test_rollover",
"index.opendistro.index_state_management.policy_id" : "test_rollover",
"index" : "test-000001",
"index_uuid" : "CgKsxFmQSIa8dWqpbSJmyA",
"policy_id" : "test_rollover",
"policy_seq_no" : -2,
"policy_primary_term" : 0,
"rolled_over" : false,
"index_creation_date" : 1667410460649,
"state" : {
"name" : "rollover",
"start_time" : 1667410766045
},
"action" : {
"name" : "rollover",
"start_time" : 1667411127803,
"index" : 0,
"failed" : false,
"consumed_retries" : 0,
"last_retry_time" : 0
},
"step" : {
"name" : "attempt_rollover",
"start_time" : 1667411127803,
"step_status" : "starting"
},
"retry_info" : {
"failed" : true,
"consumed_retries" : 0
},
"info" : {
"message" : "Previous action was not able to update IndexMetaData."
},
"enabled" : false,
"validate" : {
"validation_message" : "Missing rollover_alias index setting [index=test-000001]",
"validation_status" : "re_validating"
}
},
"total_managed_indices" : 1
}
如果你将 validate_action=false 传递给 _plugins/_ism/explain 端点，或者不传递 validate_action 值，响应将不包含错误预防验证状态和消息：
GET _plugins/_ism/explain/test-000001?validate_action=false
或者：
GET _plugins/_ism/explain/test-000001
示例响应
{
"test-000001" : {
"index.plugins.index_state_management.policy_id" : "test_rollover",
"index.opendistro.index_state_management.policy_id" : "test_rollover",
"index" : "test-000001",
"index_uuid" : "CgKsxFmQSIa8dWqpbSJmyA",
"policy_id" : "test_rollover",
"policy_seq_no" : -2,
"policy_primary_term" : 0,
"rolled_over" : false,
"index_creation_date" : 1667410460649,
"state" : {
"name" : "rollover",
"start_time" : 1667410766045
},
"action" : {
"name" : "rollover",
"start_time" : 1667411127803,
"index" : 0,
"failed" : false,
"consumed_retries" : 0,
"last_retry_time" : 0
},
"step" : {
"name" : "attempt_rollover",
"start_time" : 1667411127803,
"step_status" : "starting"
},
"retry_info" : {
"failed" : true,
"consumed_retries" : 0
},
"info" : {
"message" : "Previous action was not able to update IndexMetaData."
},
"enabled" : false
},
"total_managed_indices" : 1
}