Policies

• The states that an index can be in, including the default state for new indexes. For example, you might name your states “hot,” “warm,” “delete,” and so on. For more information, see States.
• Any actions that you want the plugin to take when an index enters a state, such as performing a rollover. For more information, see .
• The conditions that must be met for an index to move into a new state, known as transitions. For example, if an index is more than eight weeks old, you might want to move it to the “delete” state. For more information, see Transitions.

In other words, a policy defines the states that an index can be in, the actions to perform when in a state, and the conditions that must be met to transition between states.

You have complete flexibility in the way you can design your policies. You can create any state, transition to any other state, and specify any number of actions in each state.

This table lists the relevant fields of a policy.

A state is the description of the status that the managed index is currently in. A managed index can be in only one state at a time. Each state has associated actions that are executed sequentially on entering a state and transitions that are checked after all the actions have been completed.

This table lists the parameters that you can define for a state.

Actions

Actions are the steps that the policy sequentially executes on entering a specific state.

ISM executes actions in the order in which they are defined. For example, if you define actions [A,B,C,D], ISM executes action A, and then goes into a sleep period based on the cluster setting plugins.index_state_management.job_interval. Once the sleep period ends, ISM continues to execute the remaining actions. However, if ISM cannot successfully execute action A, the operation ends, and actions B, C, and D do not get executed.

Optionally, you can define an action’s timeout period, which, if exceeded, forcibly fails the action. For example, if timeout is set to 1d, and ISM has not completed the action within one day, even after retries, the action fails.

This table lists the parameters that you can define for an action.

The retry operation has the following parameters:

The following example action has a timeout period of one hour. The policy retries this action three times with an exponential backoff policy, with a delay of 10 minutes between each retry:

For a list of available unit types, see Supported units.

ISM supports the following operations:

• read_only
• replica_count
• close
• delete
• notification
• index_priority

Reduces the number of Lucene segments by merging the segments of individual shards. This operation attempts to set the index to a read-only state before starting the merging process.

{
  "force_merge": {
    "max_num_segments": 1
  }
}

read_only

Sets a managed index to be read only.

{
  "read_only": {}
}

read_write

Sets a managed index to be writeable.

{
  "read_write": {}
}

replica_count

Sets the number of replicas to assign to an index.

{
  "replica_count": {
    "number_of_replicas": 2
  }
}

For information about setting replicas, see .

Allows you to reduce the number of primary shards in your indexes. With this action, you can specify:

• The number of primary shards that the target index should contain.
• A max shard size for the primary shards in the target index.
• Specify a percentage to shrink the number of primary shards in the target index.

"shrink": {
    "num_new_shards": 1,
    "target_index_name_template": {
        "source": "_shrunken"
    },
    "aliases": [
       "my-alias": {}
    ],
    "force_unsafe": false
}

If you want to add aliases to the action, the parameter must include an array of alias objects. For example,

"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

Closes the managed index.

{
  "close": {}
}

Closing an index is a good option if you need to retain data for longer than you need to actively search it and have sufficient disk space on your data nodes. If you need to search the data again, reopening a closed index is simpler than restoring an index from a snapshot.

open

Opens a managed index.

{
  "open": {}
}

delete

Deletes a managed index.

{
  "delete": {}
}

Rolls an alias over to a new index when the managed index meets one of the rollover conditions.

Important: ISM checks the conditions for operations on every execution of the policy based on the set interval, not continuously. The rollover will be performed if the value has reached or exceeded the configured limit when the check is performed. For example with min_size configured to a value of 100GiB, ISM might check the index at 99 GiB and not perform the rollover. However, if the index has grown past the limit (e.g. 105GiB) by the next check, the operation is performed.

The index format must match the pattern: ^.*-\d+$. For example, (logs-000001). Set index.plugins.index_state_management.rollover_alias as the alias to rollover.

{
  "rollover": {
    "min_size": "50gb"
  }
}

{
  "rollover": {
    "min_doc_count": 100000000
  }
}

{
  "rollover": {
    "min_index_age": "30d"
  }
}

notification

Sends you a notification.

The destination system must return a response otherwise the notification operation throws an error.

Example 1: Chime notification

{
  "notification": {
    "destination": {
        "url": "<url>"
    },
    "message_template": {
      "source": "the index is {{ctx.index}}"
    }
  }
}

Example 2: Custom webhook notification

{
  "notification": {
    "destination": {
      "custom_webhook": {
        "url": "https://<your_webhook>"
      }
    },
    "message_template": {
      "source": "the index is {{ctx.index}}"
    }
  }
}

Example 3: Slack notification

{
  "notification": {
    "destination": {
      "slack": {
        "url": "https://hooks.slack.com/services/xxx/xxxxxx"
      }
    },
    "message_template": {
      "source": "the index is {{ctx.index}}"
    }
  }
}

You can use ctx variables in your message to represent a number of policy parameters based on the past executions of your policy. For example, if your policy has a rollover action, you can use {{ctx.action.name}} in your message to represent the name of the rollover.

The following ctx variable options are available for every policy:

Guaranteed variables

snapshot

Back up your cluster’s indexes and state. For more information about snapshots, see .

The snapshot operation has the following parameters:

{
  "snapshot": {
    "repository": "my_backup",
    "snapshot": ""
  }
}

index_priority

Set the priority for the index in a specific state. Unallocated shards of indexes are recovered in the order of their priority, whenever possible. The indexes with higher priority values are recovered first followed by the indexes with lower priority values.

The index_priority operation has the following parameter:

"actions": [
  {
    "index_priority": {
      "priority": 50
    }
  }
]

Allocate the index to a node with a specific attribute set . For example, setting require to warm moves your data only to “warm” nodes.

The allocation operation has the following parameters:

"actions": [
  {
    "allocation": {
      "require": { "temp": "warm" }
    }
  }
]

Transitions

Transitions define the conditions that need to be met for a state to change. After all actions in the current state are completed, the policy starts checking the conditions for transitions.

ISM evaluates transitions in the order in which they are defined. For example, if you define transitions: [A,B,C,D], ISM iterates through this list of transitions until it finds a transition that evaluates to true, it then stops and sets the next state to the one defined in that transition. On its next execution, ISM dismisses the rest of the transitions and starts in that new state.

If you don’t specify any conditions in a transition and leave it empty, then it’s assumed to be the equivalent of always true. This means that the policy transitions the index to this state the moment it checks.

This table lists the parameters you can define for transitions.

The conditions object has the following parameters:

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

ISM checks the conditions on every execution of the policy based on the set interval.

This example uses the cron condition to transition indexes every Saturday at 5:00 PT:

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

Note that this condition does not execute at exactly 5:00 PM; the job still executes based off the job_interval setting. Due to this variance in start time and the amount of time that it can take for actions to complete prior to checking transition conditions, we recommend against overly narrow cron expressions. For example, don’t use 15 17 * * SAT (5:15 PM on Saturday).

A window of an hour, which this example uses, is generally sufficient, but you might increase it to 2–3 hours to avoid missing the window and having to wait a week for the transition to occur. Alternately, you could use a broader expression such as * * * * SAT,SUN to have the transition occur at any time during the weekend.

For information on writing cron expressions, see .

The error_notification operation sends you a notification if your managed index fails. It notifies a single destination or notification channel with a custom message.

Set up error notifications at the policy level:

The destination system must return a response otherwise the error_notification operation throws an error.

Example 1: Chime notification

{
  "error_notification": {
    "destination": {
      "chime": {
        "url": "<url>"
      }
    },
    "message_template": {
      "source": "The index {{ctx.index}} failed during policy execution."
    }
  }
}

Example 2: Custom webhook notification

{
  "error_notification": {
    "destination": {
      "custom_webhook": {
        "url": "https://<your_webhook>"
      }
    },
    "message_template": {
    }
  }
}

Example 3: Slack notification

{
  "error_notification": {
    "destination": {
      "slack": {
        "url": "https://hooks.slack.com/services/xxx/xxxxxx"
      }
    },
    "message_template": {
      "source": "The index {{ctx.index}} failed during policy execution."
    }
  }
}

Example 4: Using a notification channel

{
  "error_notification": {
    "channel": {
      "id": "some-channel-config-id"
    },
    "message_template": {
      "source": "The index {{ctx.index}} failed during policy execution."
    }
  }

You can use the same options for ctx variables as the operation.

Sample policy with ISM template for auto rollover

The following sample template policy is for a rollover use case.

If you want to skip rollovers for an index, set index.plugins.index_state_management.rollover_skip to true in the settings of that index.

1. Create a policy with an ism_template field:

   PUT _plugins/_ism/policies/rollover_policy
   {
     "policy": {
       "description": "Example rollover policy.",
       "default_state": "rollover",
       "states": [
         {
           "name": "rollover",
           "actions": [
             {
               "rollover": {
                 "min_doc_count": 1
               }
             }
           ],
           "transitions": []
         }
       ],
       "ism_template": {
         "index_patterns": ["log*"],
         "priority": 100
       }
     }
   }

   You need to specify the index_patterns field. If you don’t specify a value for priority, it defaults to 0.

2. Set up a template with the rollover_alias as log :

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

3. Create an index with the log alias:

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

4. Index a document to trigger the rollover condition:

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

5. Verify if the policy is attached to the log-000001 index:

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

The following example policy implements a hot, warm, and delete workflow. You can use this policy as a template to prioritize resources to your indexes based on their levels of activity.

In this case, an index is initially in a hot state. After a day, it changes to a warm state, where the number of replicas increases to 5 to improve the read performance.

After 30 days, the policy moves this index into a delete state. The service sends a notification to a Chime room that the index is being deleted, and then permanently deletes it.

{
  "policy": {
    "description": "hot warm delete workflow",
    "default_state": "hot",
    "schema_version": 1,
    "states": [
      {
        "name": "hot",
        "actions": [
          {
            "rollover": {
              "min_index_age": "1d",
              "min_primary_shard_size": "30gb"
            }
          }
        ],
        "transitions": [
          {
            "state_name": "warm"
          }
        ]
      },
      {
        "name": "warm",
        "actions": [
          {
            "replica_count": {
              "number_of_replicas": 5
            }
          }
        ],
        "transitions": [
          {
            "state_name": "delete",
            "conditions": {
              "min_index_age": "30d"
            }
          }
        ]
      },
      {
        "name": "delete",
        "actions": [
          {
            "notification": {
              "destination": {
                "chime": {
                  "url": "<URL>"
                }
              },
              "message_template": {
                "source": "The index {{ctx.index}} is being deleted"
              }
            }
          },
          {
            "delete": {}
          }
        ]
      }
    ],
    "ism_template": {
      "index_patterns": ["log*"],
      "priority": 100
    }
  }
}

This diagram shows the states, transitions, and of the above policy as a finite-state machine. For more information about finite-state machines, see .