策略

策略是 JSON 文档,定义以下内容:

  • 索引可以处于的 状态,包括新索引的默认状态。例如,你可能将状态命名为 “hot”、”warm”、”delete” 等。更多信息,请参见 状态

  • 当索引进入某个状态时希望插件执行的操作,例如执行 rollover。更多信息,请参见 操作

  • 索引必须满足才能移动到新状态的条件,称为 转换。例如,如果索引超过八周,你可能希望将其移动到 “delete” 状态。更多信息,请参见 转换

换句话说,策略定义了索引可以处于的 状态、在某个状态下要执行的 操作,以及在不同状态之间 转换 必须满足的条件。

你可以完全灵活地设计策略。可以创建任何状态,转换到任何其他状态,并在每个状态中指定任意数量的操作。

下表列出了策略的相关字段。

字段 描述 类型 必需 只读
policy_id 策略的名称。 string
description 策略的人类可读描述。 string
ism_template 指定 ISM 模板以自动将策略应用于新创建的索引。 嵌套对象列表
ism_template.index_patterns 指定匹配新创建索引名称的模式。 字符串列表
ism_template.priority 指定优先级,在多个策略匹配新创建索引名称时进行区分。 number
last_updated_time 策略上次更新的时间。 timestamp
error_notification 错误通知的目标和消息模板。目标可以是 Amazon Chime、Slack 或 webhook URL。 object
default_state 使用此策略的每个索引的默认起始状态。 string
states 策略中定义的状态。 嵌套对象列表

状态

状态是托管索引当前所处状态的描述。托管索引一次只能处于一个状态。每个状态都有相关联的操作,在进入状态时会顺序执行,以及转换,在完成所有操作后会进行检查。

下表列出了可以为状态定义的参数。

字段 描述 类型 必需
name 状态的名称。 string
actions 进入状态后执行的操作。更多信息,请参见 操作 嵌套对象列表
transitions 下一个状态以及转换到这些状态所需的条件。如果不存在转换,策略假定其已完成,现在可以停止管理索引。更多信息,请参见 转换 嵌套对象列表

操作

操作是策略在进入特定状态时顺序执行的步骤。

ISM 按定义的顺序执行操作。例如,如果你定义操作 [A,B,C,D],ISM 执行操作 A,然后根据集群设置 plugins.index_state_management.job_interval 进入休眠期。休眠期结束后,ISM 继续执行剩余操作。但是,如果 ISM 无法成功执行操作 A,操作结束,操作 B、C 和 D 不会被执行。

你可以选择定义操作的超时时间,如果超过该时间,操作将强制失败。例如,如果超时设置为 1d,即使重试,ISM 在一天内仍未完成操作,操作将失败。

下表列出了可以为操作定义的参数。

参数 描述 类型 必需 默认值
timeout 操作的超时时间。接受分钟、小时和天的时间单位。 时间单位 -
retry 操作的重试配置。 object 特定于操作

retry 操作具有以下参数:

参数 描述 类型 必需 默认值
count 重试次数。 number -
backoff 重试时使用的退避策略类型。有效值为 Exponential、Constant 和 Linear。 string Exponential
delay 重试之间的等待时间。接受分钟、小时和天的时间单位。 时间单位 1 分钟

以下示例操作的超时时间为 1 小时。策略使用指数退避策略重试此操作 3 次,每次重试之间延迟 10 分钟:

"actions": {
  "timeout": "1h",
  "retry": {
    "count": 3,
    "backoff": "exponential",
    "delay": "10m"
  }
}

有关可用单位类型的列表,请参见支持的单位

ISM 支持的操作

ISM 支持以下操作:

force_merge

通过合并各个分段的段来减少 Lucene 段的数量。此操作尝试在开始合并过程之前将索引设置为 read-only 状态。

参数 描述 类型 必需
max_num_segments 要将分片减少到的段数。 number
wait_for_completion 布尔值 当设置为 false 时,请求在操作完成后立即返回,而不是在操作完成后。要使用返回的请求的任务 ID 监控操作状态,请使用任务 API。默认值为 true
task_execution_timeout 时间 显式任务执行超时。仅在 wait_for_completion 设置为 false 时有用。默认值为 1h
{
  "force_merge": {
    "max_num_segments": 1
  }
}

read_only

将托管索引设置为只读。

{
  "read_only": {}
}

为托管索引设置索引设置 index.blocks.writetrue。*注意: 此块不会阻止索引刷新。

read_write

将托管索引设置为可写。

{
  "read_write": {}
}

replica_count

设置分配给索引的副本数。

参数 描述 类型 必需
number_of_replicas 定义分配给索引的副本数。 number
{
  "replica_count": {
    "number_of_replicas": 2
  }
}

有关设置副本的信息,请参见 主分片和副本分片

shrink

允许你减少索引中的主分片数量。通过此操作,你可以指定:

  • 目标索引应包含的主分片数量。

  • 目标索引中主分片的最大分片大小。

  • 指定目标索引中主分片数量的缩小百分比。

"shrink": {
    "num_new_shards": 1,
    "target_index_name_template": {
        "source": "{{ctx.index}}_shrunken"
    },
    "aliases": [
      {
        "my-alias": {}
      }
    ],
    "switch_aliases": true,
    "force_unsafe": false
}
参数 描述 类型 示例 必需
num_new_shards 缩小索引中的最大主分片数。 整数 5 是。但是,不能与 max_shard_sizepercentage_of_source_shards 一起使用。
max_shard_size 目标索引中分片的最大大小(以字节为单位)。 关键字 5gb 是,但是,不能与 num_new_shardspercentage_of_source_shards 一起使用。
percentage_of_source_shards 要缩小的原始主分片数量的百分比。此参数表示在缩小时要使用的最小主分片数量百分比。必须在 0.0 和 1.0 之间,不包括 0.0 和 1.0。 百分比 0.5 是,但是,不能与 max_shard_sizenum_new_shards 一起使用
target_index_name_template 缩小索引的名称。接受字符串和 Mustache 变量 {{ctx.index}}{{ctx.indexUuid}} 字符串或 Mustache 模板 {"source": "{{ctx.index}}_shrunken"}
aliases 要添加到新索引的别名。 对象 myalias 否。它必须是别名对象的数组。
switch_aliases 如果为 true,将别名从源索引复制到目标索引。如果与 aliases 字段中的别名存在名称冲突,则使用 aliases 字段中的别名,而不是名称。 布尔值 true 否。默认隐式值为 false,这意味着默认情况下不复制任何别名。
force_unsafe 如果为 true,即使没有副本,也会缩小索引。 布尔值 false

如果你想在操作中添加 aliases,参数必须包括别名对象的数组。例如,

"aliases": [
  {
    "my-alias": {}
  },
  {
    "my-second-alias": {
      "is_write_index": false,
      "filter": {
        "multi_match": {
          "query": "QUEEN",
          "fields": ["speaker", "text_entry"]
        }
      },
      "index_routing" : "1",
      "search_routing" : "1"
    }
  },
]

close

关闭托管索引。

{
  "close": {}
}

关闭的索引保留在磁盘上,但不占用 CPU 或内存。你无法从关闭的索引中读取、写入或搜索。

如果你需要保留数据的时间超过你需要主动搜索的时间,并且数据节点上有足够的磁盘空间,关闭索引是一个不错的选择。如果你需要再次搜索数据,重新打开关闭的索引比从快照恢复索引更简单。

open

打开托管索引。

{
  "open": {}
}

delete

删除托管索引。

{
  "delete": {}
}

rollover

当托管索引满足其中一个滚动条件时,将别名滚动到新索引。

ISM 根据 设置的间隔每次策略执行时 检查操作的条件,而不是连续检查。如果在执行检查时值 已达到已超过 配置的限制,则执行滚动。例如,如果 min_size 配置为 100GiB 的值,ISM 可能会在 99 GiB 时检查索引,并且不执行滚动。但是,如果在下一次检查时索引增长超过限制(例如,105GiB),则执行操作。

如果需要跳过滚动操作,可以将索引设置 index.plugins.index_state_management.rollover_skip 设置为 true。例如,如果你收到错误消息 “Missing alias or not the write index…”,你可以将 index.plugins.index_state_management.rollover_skip 参数设置为 true 并重试以跳过滚动操作。

索引格式必须匹配模式:^.*-\d+$。例如,(logs-000001)。 将 index.plugins.index_state_management.rollover_alias 设置为要滚动的别名。

参数 描述 类型 示例 必需
min_size 滚动索引所需的总主分片存储的最小大小(不包括副本)。例如,如果你将 min_size 设置为 100 GiB,并且索引有 5 个主分片和 5 个副本分片,每个 20 GiB,则所有主分片的总大小为 100 GiB,因此发生滚动。请参见上面的 重要 说明。 string 20gb5mb
min_primary_shard_size 滚动索引所需的单个主分片的最小存储大小。例如,如果你将 min_primary_shard_size 设置为 30 GiB,并且索引中的 一个 主分片的大小大于条件,则发生滚动。请参见上面的 重要 说明。 string 20gb5mb
min_doc_count 滚动索引所需的最小文档数。请参见上面的 重要 说明。 number 2000000
min_index_age 滚动索引所需的最小年龄。索引年龄是其创建时间与当前时间之间的时间。支持的单位有 d(天)、h(小时)、m(分钟)、s(秒)、ms(毫秒)和 micros(微秒)。请参见上面的 重要 说明。 string 5d7h
copy_alias 控制是否将当前索引中的所有别名复制到新创建的索引。默认为 false boolean truefalse
{
  "rollover": {
    "min_size": "50gb"
  }
}
{
  "rollover": {
    "min_primary_shard_size": "30gb"
  }
}
{
  "rollover": {
    "min_doc_count": 100000000
  }
}
{
  "rollover": {
    "min_index_age": "30d"
  }
}

notification

向你发送通知。

参数 描述 类型 必需
destination 目标 URL。 Slack、Amazon Chime 或 webhook URL
message_template 消息的文本。你可以使用 Mustache 模板 向消息中添加变量。 object

目标系统 必须 返回响应,否则通知操作将抛出错误。

示例 1:Chime 通知

{
  "notification": {
    "destination": {
      "chime": {
        "url": "<url>"
      }
    },
    "message_template": {
      "source": "索引是 {% raw %}{{ctx.index}}{% endraw %}"
    }
  }
}

示例 2:自定义 webhook 通知

{
  "notification": {
    "destination": {
      "custom_webhook": {
        "url": "https://<your_webhook>"
      }
    },
    "message_template": {
      "source": "索引是 {% raw %}{{ctx.index}}{% endraw %}"
    }
  }
}

示例 3:Slack 通知

{
  "notification": {
    "destination": {
      "slack": {
        "url": "https://hooks.slack.com/services/xxx/xxxxxx "
      }
    },
    "message_template": {
      "source": "索引是 {% raw %}{{ctx.index}}{% endraw %}"
    }
  }
}

你可以在消息中使用 ctx 变量来表示基于策略过去执行的许多策略参数。例如,如果你的策略有滚动操作,你可以在消息中使用 {% raw %}{{ctx.action.name}}{% endraw %} 来表示滚动的名称。

以下 ctx 变量选项可用于每个策略:

保证变量

参数 描述 类型
index 索引的名称。 string
index_uuid 索引的 uuid。 string
policy_id 策略的名称。 string

snapshot

备份集群的索引和状态。有关快照的更多信息,请参见创建并恢复快照

snapshot 操作具有以下参数:

参数 描述 类型 必需 默认值
repository 你通过原生快照 API 操作注册的仓库名称。 string -
snapshot 快照的名称。接受字符串和 Mustache 变量 {{ctx.index}}{{ctx.indexUuid}}。如果 Mustache 变量无效,则快照名称默认为索引的名称。 string 或 Mustache 模板 -
{
  "snapshot": {
    "repository": "my_backup",
    "snapshot": "{{ctx.indexUuid}}"
  }
}

index_priority

为特定状态的索引设置优先级。尽可能按优先级顺序恢复索引的未分配分片。优先级值较高的索引先恢复,其次是优先级值较低的索引。

index_priority 操作具有以下参数:

参数 描述 类型 必需 默认值
priority 索引进入状态时的优先级。 number 1
"actions": [
  {
    "index_priority": {
      "priority": 50
    }
  }
]

allocation

将索引分配给具有特定属性集的节点。 例如,将 require 设置为 warm 仅将数据移动到 “warm” 节点。

allocation 操作具有以下参数:

参数 描述 类型 必需
require 将索引分配给具有指定属性的节点。 string
include 将索引分配给具有任何指定属性的节点。 string
exclude 不要将索引分配给具有任何指定属性的节点。 string
wait_for 等待策略执行后再将索引分配给具有指定属性的节点。 string
"actions": [
  {
    "allocation": {
      "require": { "temp": "warm" }
    }
  }
]

rollup

索引汇总 让你通过将旧数据汇总到摘要索引来定期降低数据粒度。

汇总作业可以是连续的或非连续的。使用 ISM 策略创建的汇总作业只能是非连续的。

端点

PUT _plugins/_rollup/jobs/<rollup_id>
GET _plugins/_rollup/jobs/<rollup_id>
DELETE _plugins/_rollup/jobs/<rollup_id>
POST _plugins/_rollup/jobs/<rollup_id>/_start
POST _plugins/_rollup/jobs/<rollup_id>/_stop
GET _plugins/_rollup/jobs/<rollup_id>/_explain

示例 ISM 汇总策略

{
    "policy": {
        "description": "示例汇总" ,
        "default_state": "rollup",
        "states": [
            {
                "name": "rollup",
                "actions": [
                    {
                        "rollup": {
                            "ism_rollup": {
                                "description": "通过 ISM 创建汇总",
                                "target_index": "target",
                                "page_size": 1000,
                                "dimensions": [
                                    {
                                        "date_histogram": {
                                            "fixed_interval": "60m",
                                            "source_field": "order_date",
                                            "target_field": "order_date",
                                            "timezone": "America/Los_Angeles"
                                        }
                                    },
                                    {
                                        "terms": {
                                            "source_field": "customer_gender",
                                            "target_field": "customer_gender"
                                        }
                                    },
                                    {
                                        "terms": {
                                            "source_field": "day_of_week",
                                            "target_field": "day_of_week"
                                        }
                                    }
                                ],
                                "metrics": [
                                    {
                                        "source_field": "taxless_total_price",
                                        "metrics": [
                                            {
                                                "sum": {}
                                            }
                                        ]
                                    },
                                    {
                                        "source_field": "total_quantity",
                                        "metrics": [
                                            {
                                                "avg": {}
                                            },
                                            {
                                                "max": {}
                                            }
                                        ]
                                    }
                                ]
                            }
                        }
                    }
                ],
                "transitions": []
            }
        ]
    }
}

请求体字段

创建 ISM 策略时需要请求字段。你可以参考 索引汇总 API 页面了解请求字段选项。

在仪表板中添加汇总策略

要在仪表板中添加汇总策略,请按照以下步骤操作。

  • 选择仪表板用户界面左上角的菜单按钮。

  • 在仪表板菜单中,选择 索引管理

  • 在下一个屏幕上选择 汇总作业

  • 选择 创建汇总作业 按钮。

  • 按照 创建汇总作业 向导中的步骤操作。

  • 名称 框中为策略添加名称。

  • 你可以参考 索引汇总 API 页面来配置汇总策略。

  • 最后,选择仪表板用户界面右下角的 创建 按钮。


转换

转换定义了状态改变所需满足的条件。在完成当前状态中的所有操作后,策略开始检查转换条件。

ISM 按定义的顺序评估转换。例如,如果你定义转换:[A,B,C,D],ISM 遍历此转换列表,直到找到评估为 true 的转换,然后停止并将下一个状态设置为该转换中定义的状态。在其下一次执行时,ISM 忽略其余的转换,并从该新状态开始。

如果你没有为转换指定任何条件并留空,则假定它等同于始终为真。这意味着策略在检查时立即将索引转换到此状态。

下表列出了可以为转换定义的参数。

参数 描述 类型 必需
state_name 如果满足条件,要转换到的状态的名称。 string
conditions 列出转换的条件。 list

conditions 对象具有以下参数:

参数 描述 类型 必需
min_index_age 转换所需的最小索引年龄。 string
min_rollover_age 在发生滚动后转换到下一个状态所需的最小年龄。 string
min_doc_count 转换所需的最小文档数。 number
min_size 转换所需的总主分片存储的最小大小(不包括副本)。例如,如果你将 min_size 设置为 100 GiB,并且索引有 5 个主分片和 5 个副本分片,每个 20 GiB,则所有主分片的总大小为 100 GiB,因此你的索引将转换到下一个状态。 string
cron 如果没有其他转换首先发生,则触发转换的 cron 作业。 object
cron.cron.expression 触发转换的 cron 表达式。 string
cron.cron.timezone 触发转换的时区。 string

以下示例在 30 天后将索引转换到 cold 状态:

"transitions": [
  {
    "state_name": "cold",
    "conditions": {
      "min_index_age": "30d"
    }
  }
]

ISM 根据设置的间隔在每次策略执行时检查条件。

此示例使用 cron 条件在太平洋时间每周六 5:00 转换索引:

"transitions": [
  {
    "state_name": "cold",
    "conditions": {
      "cron": {
        "cron": {
          "expression": "* 17 * * SAT",
          "timezone": "America/Los_Angeles"
        }
      }
    }
  }
]

请注意,此条件不会在下午 5:00 准时执行;作业仍然基于 job_interval 设置执行。由于开始时间的这种差异以及完成操作所需的时间,在检查转换条件之前,我们建议不要使用过窄的 cron 表达式。例如,不要使用 15 17 * * SAT(周六下午 5:15)。

此示例使用的一小时窗口通常足够,但你可以将其增加到 2-3 小时以避免错过窗口,不得不等待一周才能发生转换。或者,你可以使用更广泛的表达式,例如 * * * * SAT,SUN 以在周末的任何时间发生转换。

有关编写 cron 表达式的信息,请参见 Cron 表达式参考


错误通知

error_notification 操作在你的托管索引失败时向你发送通知。 它使用自定义消息通知单个目标或 通知通道

在策略级别设置错误通知:

{
  "policy": {
    "description": "hot warm delete workflow",
    "default_state": "hot",
    "schema_version": 1,
    "error_notification": { },
    "states": [ ]
  }
}
参数 描述 类型 必需
destination 目标 URL。 Slack、Amazon Chime 或 webhook URL 如果未指定 channel,则为是
channel 通知通道的 ID string 如果未指定 destination,则为是
message_template 消息的文本。你可以使用 Mustache 模板 向消息中添加变量。 object

目标系统 必须 返回响应,否则 error_notification 操作将抛出错误。

示例 1:Chime 通知

{
  "error_notification": {
    "destination": {
      "chime": {
        "url": "<url>"
      }
    },
    "message_template": {
      "source": "索引 {% raw %}{{ctx.index}}{% endraw %} 在策略执行期间失败。"
    }
  }
}

示例 2:自定义 webhook 通知

{
  "error_notification": {
    "destination": {
      "custom_webhook": {
        "url": "https://<your_webhook>"
      }
    },
    "message_template": {
      "source": "索引 {% raw %}{{ctx.index}}{% endraw %} 在策略执行期间失败。"
    }
  }
}

示例 3:Slack 通知

{
  "error_notification": {
    "destination": {
      "slack": {
        "url": "https://hooks.slack.com/services/xxx/xxxxxx "
      }
    },
    "message_template": {
      "source": "索引 {% raw %}{{ctx.index}}{% endraw %} 在策略执行期间失败。"
    }
  }
}

示例 4:使用通知通道

{
  "error_notification": {
    "channel": {
      "id": "some-channel-config-id"
    },
    "message_template": {
      "source": "索引 {% raw %}{{ctx.index}}{% endraw %} 在策略执行期间失败。"
    }
  }
}

你可以使用与 通知 操作相同的 ctx 变量选项。

带有 ISM 模板的示例策略用于自动滚动

以下示例模板策略用于滚动用例。

如果你想跳过索引的滚动,请将该索引的设置中的 index.plugins.index_state_management.rollover_skip 设置为 true

  1. 创建带有 ism_template 字段的策略:

    PUT _plugins/_ism/policies/rollover_policy
    {
      "policy": {
        "description": "示例滚动策略。",
        "default_state": "rollover",
        "states": [
          {
            "name": "rollover",
            "actions": [
              {
                "rollover": {
                  "min_doc_count": 1
                }
              }
            ],
            "transitions": []
          }
        ],
        "ism_template": {
          "index_patterns": ["log*"],
          "priority": 100
        }
      }
    }
    

    你需要指定 index_patterns 字段。如果你没有为 priority 指定值,它默认为 0。

  2. 设置带有 rollover_aliaslog 的模板:

    PUT _index_template/ism_rollover
    {
      "index_patterns": ["log*"],
      "template": {
       "settings": {
        "plugins.index_state_management.rollover_alias": "log"
       }
     }
    }
    
  3. 创建带有 log 别名的索引:

    PUT log-000001
    {
      "aliases": {
        "log": {
          "is_write_index": true
        }
      }
    }
    
  4. 索引文档以触发滚动条件:

    POST log/_doc
    {
      "message": "dummy"
    }
    
  5. 验证策略是否附加到 log-000001 索引:

    GET _plugins/_ism/explain/log-000001?pretty
    

别名操作的 ISM 模板示例策略

以下示例策略用于别名操作用例。

在以下示例中,第一个作业将触发滚动操作,并将创建一个新索引。接下来,将两个文档添加到两个索引中。新作业然后将导致第二个索引指向日志别名,并且由于别名操作,较旧的索引将被删除。

首先,创建 ISM 策略:

PUT /_plugins/_ism/policies/rollover_policy?pretty
{
  "policy": {
    "description": "示例滚动策略。",
    "default_state": "rollover",
    "states": [
      {
        "name": "rollover",
        "actions": [
          {
            "rollover": {
              "min_doc_count": 1
            }
          }
        ],
        "transitions": [{
            "state_name": "alias",
            "conditions": {
              "min_doc_count": "2"
            }
          }]
      },
      {
        "name": "alias",
        "actions": [
          {
            "alias": {
              "actions": [
                {
                  "remove": {
                      "alias": "log"
                  }
                }
              ]
            }
          }
        ]
      }
    ],
    "ism_template": {
      "index_patterns": ["log*"],
      "priority": 100
    }
  }
}

接下来,创建要启用策略的索引模板:

PUT /_index_template/ism_rollover?
{
  "index_patterns": ["log*"],
  "template": {
   "settings": {
    "plugins.index_state_management.rollover_alias": "log"
   }
 }
}

接下来,更改集群设置以每分钟触发作业:

PUT /_cluster/settings?pretty=true
{
  "persistent" : {
    "plugins.index_state_management.job_interval" : 1
  }
}

接下来,创建新索引:

PUT /log-000001
{
  "aliases": {
    "log": {
      "is_write_index": true
    }
  }
}

最后,向索引添加文档以触发作业:

POST /log-000001/_doc
{
  "message": "dummy"
}

你可以使用别名和索引 API 验证这些步骤:

GET /_cat/indices?pretty
GET /_cat/aliases?pretty

注意:indexremove_index 参数不允许与别名操作策略一起使用。仅允许 addremove 别名操作参数。

示例策略

以下示例策略实现了 hotwarmdelete 工作流。你可以将此策略用作模板,根据索引的活动级别优先分配资源。

在这种情况下,索引最初处于 hot 状态。7 天后,它变为 warm 状态,副本数减少到 1,并且索引移动到具有 warm 属性的节点。

30 天后,策略将此索引移动到 delete 状态。服务向 Chime 房间发送通知,告知索引正在被删除,然后永久删除它。

{
  "policy": {
    "description": "hot warm delete workflow",
    "default_state": "hot",
    "schema_version": 1,
    "states": [
      {
        "name": "hot",
        "actions": [
          {
            "rollover": {
              "min_index_age": "7d",
              "min_primary_shard_size": "30gb"
            }
          }
        ],
        "transitions": [
          {
            "state_name": "warm"
          }
        ]
      },
      {
        "name": "warm",
        "actions": [
          {
            "replica_count": {
              "number_of_replicas": 1
            }
          },
          {
            "allocation": {
              "require": {
                "temp": "warm"
              }
            }
          }
        ],
        "transitions": [
          {
            "state_name": "delete",
            "conditions": {
              "min_index_age": "30d"
            }
          }
        ]
      },
      {
        "name": "delete",
        "actions": [
          {
            "notification": {
              "destination": {
                "chime": {
                  "url": "<URL>"
                }
              },
              "message_template": {
                "source": "索引 {% raw %}{{ctx.index}}{% endraw %} 正在被删除"
              }
            }
          },
          {
            "delete": {}
          }
        ]
      }
    ],
    "ism_template": {
      "index_patterns": ["log*"],
      "priority": 100
    }
  }
}

此图显示了上述策略的 statestransitionsactions 作为有限状态机。有关有限状态机的更多信息,请参见 维基百科

Policy State Machine