Snapshot Management API

Introduced 2.1

Creates or updates an SM policy.

Request

Create:

Update:

You must provide the seq_no and primary_term parameters for an update request.

  1. POST _plugins/_sm/policies/daily-policy
  2. {
  3.   "description": "Daily snapshot policy",
  4.   "creation": {
  5.     "schedule": {
  6.       "cron": {
  7.         "expression": "0 8 * * *",
  8.         "timezone": "UTC"
  9.       }
  10.     },
  11.     "time_limit": "1h"
  12.   },
  13.   "deletion": {
  14.     "schedule": {
  15.       "cron": {
  16.         "expression": "0 1 * * *",
  17.         "timezone": "America/Los_Angeles"
  18.       }
  19.     },
  20.     "condition": {
  21.       "max_age": "7d",
  22.       "max_count": 21,
  23.       "min_count": 7
  24.     },
  25.     "time_limit": "1h"
  26.   },
  27.   "snapshot_config": {
  28.     "date_format": "yyyy-MM-dd-HH:mm",
  29.     "timezone": "America/Los_Angeles",
  30.     "indices": "*",
  31.     "repository": "s3-repo",
  32.     "ignore_unavailable": "true",
  33.     "include_global_state": "false",
  34.     "partial": "true",
  35.     "metadata": {
  36.       "any_key": "any_value"
  37.     }
  38.   },
  39.   "notification": {
  40.     "channel": {
  41.       "id": "NC3OpoEBzEoHMX183R3f"
  42.     },
  43.     "conditions": {
  44.       "creation": true,
  45.       "deletion": false,
  46.       "failure": false,
  47.       "time_limit_exceeded": false
  48.     }
  49.   }
  50. }

Response

  1. {
  2.   "_id" : "daily-policy-sm-policy",
  3.   "_version" : 5,
  4.   "_seq_no" : 54983,
  5.   "_primary_term" : 21,
  6.     "name" : "daily-policy",
  7.     "description" : "Daily snapshot policy",
  8.     "schema_version" : 15,
  9.     "creation" : {
  10.       "schedule" : {
  11.         "cron" : {
  12.           "expression" : "0 8 * * *",
  13.           "timezone" : "UTC"
  14.         }
  15.       },
  16.       "time_limit" : "1h"
  17.     },
  18.     "deletion" : {
  19.       "schedule" : {
  20.         "cron" : {
  21.           "expression" : "0 1 * * *",
  22.           "timezone" : "America/Los_Angeles"
  23.         }
  24.       },
  25.       "condition" : {
  26.         "max_age" : "7d",
  27.         "min_count" : 7,
  28.         "max_count" : 21
  29.       },
  30.       "time_limit" : "1h"
  31.     },
  32.     "snapshot_config" : {
  33.       "indices" : "*",
  34.       "metadata" : {
  35.         "any_key" : "any_value"
  36.       },
  37.       "ignore_unavailable" : "true",
  38.       "timezone" : "America/Los_Angeles",
  39.       "include_global_state" : "false",
  40.       "date_format" : "yyyy-MM-dd-HH:mm",
  41.       "repository" : "s3-repo",
  42.       "partial" : "true"
  43.     },
  44.     "schedule" : {
  45.       "interval" : {
  46.         "start_time" : 1656425122909,
  47.         "period" : 1,
  48.         "unit" : "Minutes"
  49.       }
  50.     },
  51.     "enabled" : true,
  52.     "last_updated_time" : 1656425122909,
  53.     "enabled_time" : 1656425122909,
  54.     "notification" : {
  55.       "channel" : {
  56.         "id" : "NC3OpoEBzEoHMX183R3f"
  58.       "conditions" : {
  59.         "creation" : true,
  60.         "deletion" : false,
  61.         "failure" : false,
  62.         "time_limit_exceeded" : false
  63.       }
  64.     }
  65.   }
  66. }

Parameters

You can specify the following parameters to create/update an SM policy.

Get policies

Introduced 2.1

Request

Get all SM policies:

  1. GET _plugins/_sm/policies

You can use a and specify pagination, the field to be sorted by, and sort order:

  1. GET _plugins/_sm/policies?from=0&size=20&sortField=sm_policy.name&sortOrder=desc&queryString=*

Get a specific SM policy:

  1. GET _plugins/_sm/policies/<policy_name>

Example

  1. {
  2.   "_id" : "daily-policy-sm-policy",
  3.   "_version" : 6,
  4.   "_seq_no" : 44696,
  5.   "_primary_term" : 19,
  6.   "sm_policy" : {
  7.     "name" : "daily-policy",
  8.     "description" : "Daily snapshot policy",
  9.     "schema_version" : 15,
  10.     "creation" : {
  11.       "schedule" : {
  12.         "cron" : {
  13.           "expression" : "0 8 * * *",
  14.           "timezone" : "UTC"
  15.         }
  16.       },
  17.       "time_limit" : "1h"
  18.     "deletion" : {
  19.       "schedule" : {
  21.           "expression" : "0 1 * * *",
  22.           "timezone" : "America/Los_Angeles"
  23.         }
  24.       },
  25.       "condition" : {
  26.         "max_age" : "7d",
  27.         "min_count" : 7,
  28.         "max_count" : 21
  29.       },
  30.       "time_limit" : "1h"
  31.     },
  32.     "snapshot_config" : {
  33.       "metadata" : {
  34.         "any_key" : "any_value"
  35.       },
  36.       "ignore_unavailable" : "true",
  37.       "include_global_state" : "false",
  38.       "date_format" : "yyyy-MM-dd-HH:mm",
  39.       "repository" : "s3-repo",
  40.       "partial" : "true"
  41.     },
  42.     "schedule" : {
  43.       "interval" : {
  44.         "start_time" : 1656341042874,
  45.         "period" : 1,
  46.         "unit" : "Minutes"
  47.       }
  48.     },
  49.     "enabled" : true,
  50.     "last_updated_time" : 1656341042874,
  51.     "enabled_time" : 1656341042874
  52.   }
  53. }

Introduced 2.1

Provides the enabled/disabled status and the metadata for all policies specified. Multiple policy names are separated with ,. You can also specify desired policies with a wildcard pattern.

SM uses a state machine for snapshot creation and deletion. The image on the left shows one execution period of the creation workflow, from the CREATION_START state to the CREATION_FINISHED state. Deletion workflow follows the same pattern as creation workflow.

Request

  1. GET _plugins/_sm/policies/<policy_names>/_explain

Example

  1. GET _plugins/_sm/policies/daily*/_explain

Response

  1. {
  2.   "policies" : [
  3.     {
  4.       "name" : "daily-policy",
  5.       "creation" : {
  6.         "current_state" : "CREATION_START",
  7.         "trigger" : {
  8.           "time" : 1656403200000
  9.         }
  10.       },
  11.       "deletion" : {
  12.         "current_state" : "DELETION_START",
  13.         "trigger" : {
  14.           "time" : 1656403200000
  15.         }
  16.       },
  17.       "policy_seq_no" : 44696,
  18.       "policy_primary_term" : 19,
  19.       "enabled" : true
  20.     }
  21.   ]
  22. }

The following table lists all fields for each policy in the response.

The following table lists all fields in the creation and deletion objects of each policy.

Start a policy

Introduced 2.1

Starts the policy by setting its enabled flag to true.

Request

  1. POST  _plugins/_sm/policies/<policy_name>/_start

Example

  1. POST  _plugins/_sm/policies/daily-policy/_start

Introduced 2.1

Sets the enabled flag to false for an SM policy. The policy will not run until you it.

Request

  1. POST  _plugins/_sm/policies/<policy_name>/_stop

Example

  1. POST  _plugins/_sm/policies/daily-policy/_stop

Response

  1. {
  2.   "acknowledged" : true
  3. }

Delete a policy

Introduced 2.1

Request

  1. DELETE  _plugins/_sm/policies/<policy_name>

Example

  1. DELETE _plugins/_sm/policies/daily-policy
  1. {
  2.   "_index" : ".opendistro-ism-config",
  3.   "_id" : "daily-policy-sm-policy",
  4.   "_version" : 8,
  5.   "result" : "deleted",
  6.   "forced_refresh" : true,
  7.   "_shards" : {
  8.     "total" : 2,
  9.     "successful" : 2,
  10.     "failed" : 0
  11.   },
  12.   "_seq_no" : 45366,