快照管理 API
使用快照管理 (SM) API 自动化创建快照。
目录
创建或更新策略
2.1 版本引入
创建或更新 SM 策略。
请求
创建
POST _plugins/_sm/policies/<policy_name>
更新
PUT _plugins/_sm/policies/<policy_name>?if_seq_no=0&if_primary_term=1
对于更新请求，您必须提供 seq_no 和 primary_term 参数。
示例
POST _plugins/_sm/policies/daily-policy
{
"description": "Daily snapshot policy",
"creation": {
"schedule": {
"cron": {
"expression": "0 8 * * *",
"timezone": "UTC"
}
},
"time_limit": "1h"
},
"deletion": {
"schedule": {
"cron": {
"expression": "0 1 * * *",
"timezone": "America/Los_Angeles"
}
},
"condition": {
"max_age": "7d",
"max_count": 21,
"min_count": 7
},
"time_limit": "1h"
},
"snapshot_config": {
"date_format": "yyyy-MM-dd-HH:mm",
"timezone": "America/Los_Angeles",
"indices": "*",
"repository": "s3-repo",
"ignore_unavailable": "true",
"include_global_state": "false",
"partial": "true",
"metadata": {
"any_key": "any_value"
}
},
"notification": {
"channel": {
"id": "NC3OpoEBzEoHMX183R3f"
},
"conditions": {
"creation": true,
"deletion": false,
"failure": false,
"time_limit_exceeded": false
}
}
}
响应
{
"_id" : "daily-policy-sm-policy",
"_version" : 5,
"_seq_no" : 54983,
"_primary_term" : 21,
"sm_policy" : {
"name" : "daily-policy",
"description" : "Daily snapshot policy",
"schema_version" : 15,
"creation" : {
"schedule" : {
"cron" : {
"expression" : "0 8 * * *",
"timezone" : "UTC"
}
},
"time_limit" : "1h"
},
"deletion" : {
"schedule" : {
"cron" : {
"expression" : "0 1 * * *",
"timezone" : "America/Los_Angeles"
}
},
"condition" : {
"max_age" : "7d",
"min_count" : 7,
"max_count" : 21
},
"time_limit" : "1h"
},
"snapshot_config" : {
"indices" : "*",
"metadata" : {
"any_key" : "any_value"
},
"ignore_unavailable" : "true",
"timezone" : "America/Los_Angeles",
"include_global_state" : "false",
"date_format" : "yyyy-MM-dd-HH:mm",
"repository" : "s3-repo",
"partial" : "true"
},
"schedule" : {
"interval" : {
"start_time" : 1656425122909,
"period" : 1,
"unit" : "Minutes"
}
},
"enabled" : true,
"last_updated_time" : 1656425122909,
"enabled_time" : 1656425122909,
"notification" : {
"channel" : {
"id" : "NC3OpoEBzEoHMX183R3f"
},
"conditions" : {
"creation" : true,
"deletion" : false,
"failure" : false,
"time_limit_exceeded" : false
}
}
}
}
参数
您可以指定以下参数来创建/更新 SM 策略。
| 参数 | 类型 | 描述 |
|---|---|---|
description | 字符串 | SM 策略的描述。可选。 |
enabled | 布尔型 | 创建时是否启用此 SM 策略？可选。 |
snapshot_config | 对象 | 快照创建的配置选项。必需。 |
snapshot_config.date_format | 字符串 | 快照名称格式为 <policy_name>-<date>-<random number>。date_format 指定快照名称中日期的格式。支持 OpenSearch 支持的所有日期格式。可选。默认值为 “yyyy-MM-dd’T’HH:mm:ss”。 |
snapshot_config.date_format_timezone | 字符串 | 快照名称格式为 <policy_name>-<date>-<random number>。date_format_timezone 指定快照名称中日期所用的时区。可选。默认值为 UTC。 |
snapshot_config.indices | 字符串 | 快照中索引的名称。多个索引名称用 , 分隔。支持通配符 (*)。可选。默认值为 * (所有索引)。 |
snapshot_config.repository | 字符串 | 存储快照的仓库。必需。 |
snapshot_config.ignore_unavailable | 布尔型 | 是否忽略不可用的索引？可选。默认值为 false。 |
snapshot_config.include_global_state | 布尔型 | 是否包含集群状态？可选。默认值为 true，因为有安全插件的注意事项。 |
snapshot_config.partial | 布尔型 | 是否允许部分快照？可选。默认值为 false。 |
snapshot_config.metadata | 对象 | 以键/值对形式表示的元数据。可选。 |
creation | 对象 | 快照创建的配置。必需。 |
creation.schedule | 字符串 | 用于创建快照的 cron 调度。必需。 |
creation.time_limit | 字符串 | 设置等待快照创建完成的最长时间。如果 time_limit 长于计划的快照间隔时间，则在 time_limit 过去之前不会进行任何计划的快照。例如，如果 time_limit 设置为 35 分钟，并且从午夜开始每 30 分钟拍摄一次快照，则会拍摄 00:00 和 01:00 的快照，但会跳过 00:30 的快照。可选。 |
deletion | 对象 | 快照删除的配置。可选。默认是保留所有快照。 |
deletion.schedule | 字符串 | 用于删除快照的 cron 调度。可选。默认是使用必需的 creation.schedule。 |
deletion.time_limit | 字符串 | 设置等待快照删除完成的最长时间。可选。 |
deletion.delete_condition | 对象 | 快照删除的条件。可选。 |
deletion.delete_condition.max_count | 整数 | 要保留的最大快照数量。可选。 |
deletion.delete_condition.max_age | 字符串 | 快照保留的最长时间。可选。 |
deletion.delete_condition.min_count | 整数 | 要保留的最小快照数量。可选。默认值为 1。 |
notification | 对象 | 定义 SM 事件的通知。可选。 |
notification.channel | 对象 | 定义通知渠道。在设置 SM 通知之前，您必须创建并配置通知渠道。必需。 |
notification.channel.id | 字符串 | 用于通知的渠道 ID。要获取所有已创建渠道的 ID，请使用 GET _plugins/_notifications/configs。必需。 |
notification.conditions | 对象 | 您希望收到通知的 SM 事件。将您感兴趣的事件设置为 true。 |
notification.conditions.creation | 布尔型 | 您是否希望收到快照创建的通知？可选。默认值为 true。 |
notification.conditions.deletion | 布尔型 | 您是否希望收到快照删除的通知？可选。默认值为 false。 |
notification.conditions.failure | 布尔型 | 您是否希望收到创建或删除失败的通知？可选。默认值为 false。 |
notification.conditions.time_limit_exceeded | 布尔型 | 当快照操作耗时超过 time_limit 时，您是否希望收到通知？可选。默认值为 false。 |
获取策略
2.1 版本引入
获取 SM 策略。
请求
获取所有 SM 策略
GET _plugins/_sm/policies
您可以使用查询字符串并指定分页、排序字段和排序顺序。
GET _plugins/_sm/policies?from=0&size=20&sortField=sm_policy.name&sortOrder=desc&queryString=*
获取特定 SM 策略
GET _plugins/_sm/policies/<policy_name>
示例
GET _plugins/_sm/policies/daily-policy
响应
{
"_id" : "daily-policy-sm-policy",
"_version" : 6,
"_seq_no" : 44696,
"_primary_term" : 19,
"sm_policy" : {
"name" : "daily-policy",
"description" : "Daily snapshot policy",
"schema_version" : 15,
"creation" : {
"schedule" : {
"cron" : {
"expression" : "0 8 * * *",
"timezone" : "UTC"
}
},
"time_limit" : "1h"
},
"deletion" : {
"schedule" : {
"cron" : {
"expression" : "0 1 * * *",
"timezone" : "America/Los_Angeles"
}
},
"condition" : {
"max_age" : "7d",
"min_count" : 7,
"max_count" : 21
},
"time_limit" : "1h"
},
"snapshot_config" : {
"metadata" : {
"any_key" : "any_value"
},
"ignore_unavailable" : "true",
"include_global_state" : "false",
"date_format" : "yyyy-MM-dd-HH:mm",
"repository" : "s3-repo",
"partial" : "true"
},
"schedule" : {
"interval" : {
"start_time" : 1656341042874,
"period" : 1,
"unit" : "Minutes"
}
},
"enabled" : true,
"last_updated_time" : 1656341042874,
"enabled_time" : 1656341042874
}
}
解释
2.1 版本引入
提供所有指定策略的启用/禁用状态和元数据。多个策略名称用 , 分隔。您还可以使用通配符模式指定所需的策略。
SM 使用状态机进行快照创建和删除。左侧图像显示了创建工作流的一个执行周期，从 CREATION_START 状态到 CREATION_FINISHED 状态。删除工作流遵循与创建工作流相同的模式。
创建工作流从 CREATION_START 状态开始，并持续检查是否满足创建 cron 调度中的条件。条件满足后，创建工作流切换到 CREATION_CONDITION_MET 状态并继续到 CREATING 状态。CREATING 状态异步调用创建快照 API，然后等待快照创建在 CREATION_FINISHED 状态结束。一旦快照创建结束，创建工作流回到 CREATION_START 状态，循环继续。metadata.creation 和 metadata.deletion 的 current_state 字段返回状态机的当前状态。
请求
GET _plugins/_sm/policies/<policy_names>/_explain
示例
GET _plugins/_sm/policies/daily*/_explain
响应
{
"policies" : [
{
"name" : "daily-policy",
"creation" : {
"current_state" : "CREATION_START",
"trigger" : {
"time" : 1656403200000
}
},
"deletion" : {
"current_state" : "DELETION_START",
"trigger" : {
"time" : 1656403200000
}
},
"policy_seq_no" : 44696,
"policy_primary_term" : 19,
"enabled" : true
}
]
}
下表列出了响应中每个策略的所有字段。
| 字段 | 描述 |
|---|---|
名称 | SM 策略的名称。 |
creation | 有关最新创建操作的信息。请参阅下面的子字段。 |
deletion | 有关最新删除操作的信息。请参阅下面的子字段。 |
policy_seq_no policy_primary_term | SM 策略的版本。 |
enabled | 策略是否正在运行？ |
下表列出了每个策略的 creation 和 deletion 对象中的所有字段。
| 字段 | 描述 |
|---|---|
current_state | 运行上述快照创建/删除的状态机的当前状态。 |
trigger.time | 下一次创建/删除执行时间，单位为自 epoch 以来的毫秒数。 |
latest_execution | 描述最新的创建/删除执行。 |
latest_execution.status | 最新创建/删除的执行状态。可能的值有：IN_PROGRESS: 快照创建/删除已开始。SUCCESS: 快照创建/删除已成功完成。RETRYING: 创建/删除尝试失败。它将重试三次。FAILED: 创建/删除尝试在三次重试后失败。结束当前执行周期，进入下一个执行周期。TIME_LIMIT_EXCEEDED: 创建/删除时间超过策略中设置的 time_limit。结束当前执行周期，进入下一个执行周期。 |
latest_execution.start_time | 最新执行的开始时间，单位为自 epoch 以来的毫秒数。 |
latest_execution.end_time | 最新执行的结束时间，单位为自 epoch 以来的毫秒数。 |
latest_execution.info.message | 描述最新执行状态的用户友好消息。 |
latest_execution.info.cause | 如果最新执行失败，包含失败原因。 |
retry.count | 剩余的执行重试次数。 |
启动策略
2.1 版本引入
通过将其 enabled 标志设置为 true 来启动策略。
请求
POST _plugins/_sm/policies/<policy_name>/_start
示例
POST _plugins/_sm/policies/daily-policy/_start
响应
{
"acknowledged" : true
}
停止策略
2.1 版本引入
将 SM 策略的 enabled 标志设置为 false。该策略将不会运行，直到您启动它。
请求
POST _plugins/_sm/policies/<policy_name>/_stop
示例
POST _plugins/_sm/policies/daily-policy/_stop
响应
{
"acknowledged" : true
}
删除策略
2.1 版本引入
删除指定的 SM 策略。
请求
DELETE _plugins/_sm/policies/<policy_name>
示例
DELETE _plugins/_sm/policies/daily-policy
响应
{
"_index" : ".opendistro-ism-config",
"_id" : "daily-policy-sm-policy",
"_version" : 8,
"result" : "deleted",
"forced_refresh" : true,
"_shards" : {
"total" : 2,
"successful" : 2,
"failed" : 0
},
"_seq_no" : 45366,
"_primary_term" : 20
}