[[actions]]
= Actions

[partintro]
--

Actions are the tasks which Curator can perform on your indices.  Snapshots,
once created, can only be deleted.

* <<alias,Alias>>
* <<allocation,Allocation>>
* <<close,Close>>
* <<cluster_routing,Cluster Routing>>
* <<cold2frozen,Cold2Frozen>>
* <<create_index,Create Index>>
* <<delete_indices,Delete Indices>>
* <<delete_snapshots,Delete Snapshots>>
* <<forcemerge,forceMerge>>
* <<index_settings,Index Settings>>
* <<open,Open>>
* <<reindex,Reindex>>
* <<replicas,Replicas>>
* <<restore,Restore>>
* <<rollover,Rollover>>
* <<shrink,Shrink>>
* <<snapshot,Snapshot>>
--

[[alias]]
== Alias

[source,yaml]
-------------
action: alias
description: "Add/Remove selected indices to or from the specified alias"
options:
  name: alias_name
add:
  filters:
  - filtertype: ...
remove:
  filters:
  - filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action adds and/or removes indices from the alias identified by
 <<option_name,name>>

The <<filters,filters>> under the `add` and `remove` directives define which
indices will be added and/or removed.  This is an atomic action, so adds and
removes happen instantaneously.

The <<option_extra_settings,extra_settings>> option allows the addition of extra
settings with the `add` directive.  These settings are ignored for `remove`.  An
example of how these settings can be used to create a filtered alias might be:

[source,yaml]
-------------
action: alias
description: "Add/Remove selected indices to or from the specified alias"
options:
  name: alias_name
  extra_settings:
    filter:
      term:
        user: kimchy
add:
  filters:
  - filtertype: ...
remove:
  filters:
  - filtertype: ...
-------------

WARNING: Before creating a filtered alias, first ensure that the fields already
  exist in the mapping.

Learn more about adding filtering and routing to aliases in the
{ref}/indices-aliases.html[Elasticsearch Alias API documentation].


=== Required settings

* <<option_name,name>>

=== Optional settings

* <<option_warn_if_no_indices,warn_if_no_indices>>
* <<option_extra_settings,extra_settings>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_alias,here>>.



[[allocation]]
== Allocation

[source,yaml]
-------------
action: allocation
description: "Apply shard allocation filtering rules to the specified indices"
options:
  key: ...
  value: ...
  allocation_type: ...
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action changes the shard routing allocation for the selected indices.

See {ref}/shard-allocation-filtering.html for more information.

You can optionally set `wait_for_completion` to `True`
to have Curator wait for the shard routing to complete before continuing:

[source,yaml]
-------------
action: allocation
description: "Apply shard allocation filtering rules to the specified indices"
options:
  key: ...
  value: ...
  allocation_type: ...
  wait_for_completion: True
  max_wait: 300
  wait_interval: 10
filters:
- filtertype: ...
-------------

This configuration will wait for a maximum of 300 seconds for shard routing and
reallocation to complete before giving up.  A `max_wait` value of `-1` will wait
indefinitely.  Curator will poll for completion at `10` second intervals, as
defined by `wait_interval`.

=== Required settings

* <<option_key,key>>

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_allocation_type,allocation_type>>
* <<option_value,value>>
* <<option_wfc,wait_for_completion>>
* <<option_max_wait,max_wait>>
* <<option_wait_interval,wait_interval>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_allocation,here>>.



[[close]]
== Close

[source,yaml]
-------------
action: close
description: "Close selected indices"
options:
  delete_aliases: false
  skip_flush: false
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action closes the selected indices, and optionally deletes associated
aliases beforehand.

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_delete_aliases,delete_aliases>>
* <<option_skip_flush,skip_flush>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_close,here>>.

[[cluster_routing]]
== Cluster Routing

[source,yaml]
-------------
action: cluster_routing
description: "Apply routing rules to the entire cluster"
options:
  routing_type:
  value: ...
  setting: enable
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action changes the shard routing allocation for the selected indices.

See {ref}/shards-allocation.html for more information.

You can optionally set `wait_for_completion` to `True`
to have Curator wait for the shard routing to complete before continuing:

[source,yaml]
-------------
action: cluster_routing
description: "Apply routing rules to the entire cluster"
options:
  routing_type:
  value: ...
  setting: enable
  wait_for_completion: True
  max_wait: 300
  wait_interval: 10
-------------

This configuration will wait for a maximum of 300 seconds for shard routing and
reallocation to complete before giving up.  A `max_wait` value of `-1` will wait
indefinitely.  Curator will poll for completion at `10` second intervals, as
defined by `wait_interval`.

=== Required settings

* <<option_routing_type,routing_type>>
* <<option_value,value>>
* <<option_setting,setting>> Currently must be set to `enable`.  This setting
  is a placeholder for potential future expansion.

=== Optional settings

* <<option_wfc,wait_for_completion>>
* <<option_max_wait,max_wait>>
* <<option_wait_interval,wait_interval>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_cluster_routing,here>>.



[[cold2frozen]]
== Cold2Frozen

IMPORTANT: This action is for an unusual case where an index is a mounted, searchable snapshot in
  the cold tier and is not associated with an ILM policy. This action will not work with an index
  associated with an ILM policy regardless of the value of `allow_ilm_indices`.

[source,yaml]
-------------
action: cold2frozen
description: "Migrate non-ILM indices from the cold tier to the frozen tier"
options:
  index_settings: {}
  ignore_index_settings: []
  wait_for_completion: True
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action migrates the selected non-ILM indices from the cold tier to the frozen tier.
You may well ask why this action is here and why it is limited to non-ILM indices. The answer
is "redacted data." If an index must be restored from the cold tier to be live so that sensitive
data can be redacted, at present, it must be disassociated from an ILM policy to accomplish this.
If you forcemerge and re-snapshot the redacted index, you can still put it in the cold or frozen
tier, but it will not be associated with an ILM policy any more. This custom action is for moving
that manually re-mounted cold tier index to the frozen tier, preserving the aliases it currently
has.

=== index_settings

Settings that should be added to the index when it is mounted. This should be a YAML dictionary
containing anything under what would normally appear in `settings`.

See {ref}/searchable-snapshots-api-mount-snapshot.html

[source,yaml]
-------------
action: cold2frozen
description: "Migrate non-ILM indices from the cold tier to the frozen tier"
options:
  index_settings:
    routing:
      allocation:
        include:
          _tier_preference: data_frozen
  ignore_index_settings: []
  wait_for_completion: True
filters:
- filtertype: ...
-------------

NOTE: If unset, the default behavior is to ensure that the `_tier_preference` is `data_frozen`,
  if available. If it is not, Curator will assess which data tiers are available in your cluster
  and use those from coldest to warmest, e.g. `data_cold,data_warm,data_hot`. If none of these are
  available, it will default to `data_content`.

=== ignore_index_settings

This should be a YAML list of index settings the migrated index should ignore after mount.

See {ref}/searchable-snapshots-api-mount-snapshot.html

[source,yaml]
-------------
action: cold2frozen
description: "Migrate non-ILM indices from the cold tier to the frozen tier"
options:
  index_settings:
  ignore_index_settings:
    - 'index.refresh_interval'
  wait_for_completion: True
filters:
- filtertype: ...
-------------

NOTE: If unset, the default behavior is to ensure that the `index.refresh_interval` is ignored.

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_wfc,wait_for_completion>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>



[[create_index]]
== Create Index

[source,yaml]
-------------
action: create_index
description: "Create index as named"
options:
  name: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action creates the named index.  There are multiple different ways to
configure how the name is represented.

=== Manual naming

[source,yaml]
-------------
action: create_index
description: "Create index as named"
options:
  name: myindex
  # ...
-------------

In this case, what you see is what you get. An index named `myindex` will be
created

=== Python strftime

[source,yaml]
-------------
action: create_index
description: "Create index as named"
options:
  name: 'myindex-%Y.%m'
  # ...
-------------

For the `create_index` action, the <<option_name,name>> option can contain
Python strftime strings.  The method for doing so is described in detail,
including which strftime strings are acceptable, in the documentation for the
<<option_name,name>> option.

=== Date Math

[source,yaml]
-------------
action: create_index
description: "Create index as named"
options:
  name: '<logstash-{now/d+1d}>'
  # ...
-------------



For the `create_index` action, the <<option_name,name>> option can be in
Elasticsearch
{ref}/api-conventions.html#api-date-math-index-names[date math] format.  This allows index names
containing dates to use deterministic math to set a date name in the past or the
future.

For example, if today's date were 2017-03-27, the name `<logstash-{now/d}>` will
create an index named `logstash-2017.03.27`. If you wanted to create
_tomorrow's_ index, you would use the name `<logstash-{now/d+1d}>`, which adds 1
day.  This pattern creates an index named `logstash-2017.03.28`.  For many more
configuration options, read the Elasticsearch
{ref}/api-conventions.html#api-date-math-index-names[date math] documentation.

=== Extra Settings

The <<option_extra_settings,extra_settings>> option allows the addition of extra
settings, such as index settings and mappings.  An example of how these settings
can be used to create an index might be:

[source,yaml]
-------------
action: create_index
description: "Create index as named"
options:
  name: myindex
  # ...
  extra_settings:
    settings:
      number_of_shards: 1
      number_of_replicas: 0
    mappings:
      type1:
        properties:
          field1:
            type: string
            index: not_analyzed
-------------

=== Required settings

* <<option_name,name>>

=== Optional settings

* <<option_extra_settings,extra_settings>> No default value.  You can add any
    acceptable index settings and mappings as nested YAML.  See the
    {ref}/indices-create-index.html[Elasticsearch Create Index API documentation]
    for more information.
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_create_index,here>>.



[[delete_indices]]
== Delete Indices

[source,yaml]
-------------
action: delete_indices
description: "Delete selected indices"
options:
  continue_if_exception: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action deletes the selected indices.

In clusters which are overcrowded with indices, or a high number of shards per
node, deletes can take a longer time to process.  In such cases, it may be
helpful to set a higher timeout than is set in the
<<configfile, configuration file>>.  You can override that <<request_timeout,request_timeout>>
as follows:

[source,yaml]
-------------
action: delete_indices
description: "Delete selected indices"
options:
  timeout_override: 300
  continue_if_exception: False
filters:
- filtertype: ...
-------------

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_delete_indices,here>>.



[[delete_snapshots]]
== Delete Snapshots

[source,yaml]
-------------
action: delete_snapshots
description: "Delete selected snapshots from 'repository'"
options:
  repository: ...
  retry_interval: 120
  retry_count: 3
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action deletes the selected snapshots from the selected
<<option_repository,repository>>.  If a snapshot is currently underway, Curator
will retry up to <<option_retry_count,retry_count>> times, with a delay of
<<option_retry_interval,retry_interval>> seconds between retries.


=== Required settings

* <<option_repository,repository>>

=== Optional settings

* <<option_retry_interval,retry_interval>>
* <<option_retry_count,retry_count>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_delete_snapshots,here>>.


[[forcemerge]]
== Forcemerge

[source,yaml]
-------------
action: forcemerge
description: >-
  Perform a forceMerge on selected indices to 'max_num_segments' per shard
options:
  max_num_segments: 2
  timeout_override: 21600
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action performs a forceMerge on the selected indices, merging them to
<<option_mns,max_num_segments>> per shard.

WARNING: A {ref}/indices-forcemerge.html#indices-forcemerge[`forcemerge`] should
    never be executed on an index that is actively receiving data.  It should
    only ever be performed on indices where no more documents are ever
    anticipated to be added in the future.

You can optionally pause between each merge for <<option_delay,delay>> seconds
to allow the cluster to quiesce:

[source,yaml]
-------------
action: forcemerge
description: >-
  Perform a forceMerge on selected indices to 'max_num_segments' per shard
options:
  max_num_segments: 2
  timeout_override: 21600
  delay: 120
filters:
- filtertype: ...
-------------


=== Required settings

* <<option_mns,max_num_segments>>

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_delay,delay>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_forcemerge,here>>.


[[index_settings]]
== Index Settings

[source,yaml]
-------------
action: index_settings
description: "Change settings for selected indices"
options:
  index_settings:
    index:
      refresh_interval: 5s
  ignore_unavailable: False
  preserve_existing: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action updates the specified index settings for the selected indices.

[IMPORTANT]
=======================
While Elasticsearch allows for either dotted notation of index settings, such as

[source,json]
-------------
PUT /indexname/_settings
{
  "index.blocks.read_only": true
}
-------------

or in nested structure, like this:

[source,json]
-------------
PUT /indexname/_settings
{
  "index": {
    "blocks": {
      "read_only": true
    }
  }
}
-------------

In order to appropriately detect
https://www.elastic.co/guide/en/elasticsearch/reference/5.4/index-modules.html#_static_index_settings[static]
vs.
https://www.elastic.co/guide/en/elasticsearch/reference/5.4/index-modules.html#dynamic-index-settings[dynamic]
settings, and to be able to verify configurational integrity in the YAML file,
**Curator does not support using dotted notation.**

=======================

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>
* <<option_ignore,ignore_unavailable>>
* <<option_preserve_existing,preserve_existing>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_index_settings,here>>.

[[open]]
== Open

[source,yaml]
-------------
action: open
description: "open selected indices"
options:
  continue_if_exception: False
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action opens the selected indices.

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_open,here>>.



[[reindex]]
== Reindex

[source,yaml]
-------------
actions:
  1:
    description: "Reindex index1 into index2"
    action: reindex
    options:
      wait_interval: 9
      max_wait: -1
      request_body:
        source:
          index: index1
        dest:
          index: index2
    filters:
    - filtertype: none
-------------

There are many options for the reindex option.  The best place to start is in
the <<option_request_body,request_body documentation>> to see how to configure
this action.  All other options are as follows.

=== Required settings

* <<option_request_body,request_body>>

=== Optional settings

* <<option_refresh,refresh>>
* <<option_remote_certificate,remote_certificate>>
* <<option_remote_client_cert,remote_client_cert>>
* <<option_remote_client_key,remote_client_key>>
* <<option_remote_filters,remote_filters>>
* <<option_remote_url_prefix,remote_url_prefix>>
* <<option_request_body,request_body>>
* <<option_requests_per_second,requests_per_second>>
* <<option_slices,slices>>
* <<option_timeout,timeout>>
* <<option_wait_for_active_shards,wait_for_active_shards>>
* <<option_wfc,wait_for_completion>>
* <<option_max_wait,max_wait>>
* <<option_wait_interval,wait_interval>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>
* <<option_migration_prefix,migration_prefix>>
* <<option_migration_suffix,migration_suffix>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_reindex,here>>.

=== Compatibility

Generally speaking, the Curator should be able to perform a remote reindex from
any version of Elasticsearch, 1.4 and newer. Strictly speaking, the Reindex API
in Elasticsearch _is_ able to reindex from older clusters, but Curator cannot be
used to facilitate this due to Curator's dependency on changes released in 1.4.


[[replicas]]
== Replicas

[source,yaml]
-------------
action: replicas
description: >- Set the number of replicas per shard for selected
    indices to 'count'
options:
  count: ...
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action will set the number of replicas per shard to the value of
<<option_count,count>>.

You can optionally set `wait_for_completion` to `True` to have Curator wait for
the replication operation to complete before continuing:

[source,yaml]
-------------
action: replicas
description: >- Set the number of replicas per shard for selected
    indices to 'count'
options:
  count: ...
  wait_for_completion: True
  max_wait: 600
  wait_interval: 10
filters:
- filtertype: ...
-------------

This configuration will wait for a maximum of 600 seconds for all index replicas
to be complete before giving up.  A `max_wait` value of `-1` will wait
indefinitely.  Curator will poll for completion at `10` second intervals, as
defined by `wait_interval`.

=== Required settings

* <<option_count,count>>

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_wfc,wait_for_completion>>
* <<option_max_wait,max_wait>>
* <<option_wait_interval,wait_interval>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_replicas,here>>.



[[restore]]
== Restore

[source,yaml]
-------------
actions:
  1:
    action: restore
    description: >-
      Restore all indices in the most recent snapshot with state SUCCESS.  Wait
      for the restore to complete before continuing.  Do not skip the repository
      filesystem access check.  Use the other options to define the index/shard
      settings for the restore.
    options:
      repository:
      # If name is blank, the most recent snapshot by age will be selected
      name:
      # If indices is blank, all indices in the snapshot will be restored
      indices:
      wait_for_completion: True
      max_wait: 3600
      wait_interval: 10
    filters:
    - filtertype: state
      state: SUCCESS
      exclude:
    - filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action will restore indices from the indicated
<<option_repository,repository>>, from the most recent snapshot identified by
the applied filters, or the snapshot identified by <<option_name,name>>.

=== Renaming indices on restore

You can cause indices to be renamed at restore with the
<<option_rename_pattern,rename_pattern>> and
<<option_rename_replacement,rename_replacement>> options:

[source,yaml]
-------------
actions:
  1:
    action: restore
    description: >-
      Restore all indices in the most recent snapshot with state SUCCESS.  Wait
      for the restore to complete before continuing.  Do not skip the repository
      filesystem access check.  Use the other options to define the index/shard
      settings for the restore.
    options:
      repository:
      # If name is blank, the most recent snapshot by age will be selected
      name:
      # If indices is blank, all indices in the snapshot will be restored
      indices:
      rename_pattern: 'index(.+)'
      rename_replacement: 'restored_index$1'
      wait_for_completion: True
      max_wait: 3600
      wait_interval: 10
    filters:
    - filtertype: state
      state: SUCCESS
      exclude:
    - filtertype: ...
-------------

In this configuration, Elasticsearch will capture whatever appears after `index`
and put it after `restored_index`.  For example, if I was restoring
`index-2017.03.01`, the resulting index would be renamed to
`restored_index-2017.03.01`.

=== Extra settings

The <<option_extra_settings,extra_settings>> option allows the addition of extra
settings, such as index settings.  An example of how these settings
can be used to change settings for an index being restored might be:

[source,yaml]
-------------
actions:
  1:
    action: restore
    description: >-
      Restore all indices in the most recent snapshot with state SUCCESS.  Wait
      for the restore to complete before continuing.  Do not skip the repository
      filesystem access check.  Use the other options to define the index/shard
      settings for the restore.
    options:
      repository:
      # If name is blank, the most recent snapshot by age will be selected
      name:
      # If indices is blank, all indices in the snapshot will be restored
      indices:
      extra_settings:
        index_settings:
          number_of_replicas: 0
      wait_for_completion: True
      max_wait: 3600
      wait_interval: 10
    filters:
    - filtertype: state
      state: SUCCESS
      exclude:
    - filtertype: ...
-------------

In this case, the number of replicas will be applied to the restored indices.

For more information see the {ref}/snapshots-restore-snapshot.html[official Elasticsearch Documentation].

=== Required settings

* <<option_repository,repository>>

=== Optional settings

* <<option_name,name>>
* <<option_include_aliases,include_aliases>>
* <<option_indices,indices>>
* <<option_ignore,ignore_unavailable>>
* <<option_include_gs,include_global_state>>
* <<option_partial,partial>>
* <<option_rename_pattern,rename_pattern>>
* <<option_rename_replacement,rename_replacement>>
* <<option_extra_settings,extra_settings>>
* <<option_wfc,wait_for_completion>>
* <<option_max_wait,max_wait>>
* <<option_wait_interval,wait_interval>>
* <<option_skip_fsck,skip_repo_fs_check>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_restore,here>>.



[[rollover]]
== Rollover

[source,yaml]
-------------
action: rollover
description: >-
  Rollover the index associated with alias 'aliasname', which should be in the
  form of prefix-000001 (or similar), or prefix-YYYY.MM.DD-1.
options:
  name: aliasname
  conditions:
    max_age: 1d
    max_docs: 1000000
    max_size: 5gb
-------------

This action uses the
{ref}/indices-rollover-index.html[Elasticsearch Rollover API] to create a new
index, if any of the described conditions are met.

IMPORTANT: When choosing `conditions`, **any** one of
<<option_max_age,max_age>>, <<option_max_docs,max_docs>>,
<<option_max_size,max_size>>, **or any combination of the three** may be used.
If multiple are used, then the specified condition for any one of them must be
matched for the rollover to occur.

WARNING: If one or more of the <<option_max_age,max_age>>,
<<option_max_docs,max_docs>>, or <<option_max_size,max_size>> options are
present, they must each have a value. Because there are no default values,
none of these conditions can be left empty, or Curator will generate an error.

=== Extra settings

The <<option_extra_settings,extra_settings>> option allows the addition of extra
index settings (but not mappings).  An example of how these settings can be used
might be:

[source,yaml]
-------------
action: rollover
description: >-
  Rollover the index associated with alias 'aliasname', which should be in the
  form of prefix-000001 (or similar), or prefix-YYYY.MM.DD-1.
options:
  name: aliasname
  conditions:
    max_age: 1d
    max_docs: 1000000
  extra_settings:
    index.number_of_shards: 3
    index.number_of_replicas: 1
  timeout_override:
  continue_if_exception: False
  disable_action: False
-------------

=== Required settings

* <<option_name,name>> The alias name
* <<option_max_age,max_age>> The maximum age that is allowed before triggering
  a rollover. This _must_ be nested under `conditions:`. There is no default
  value. If this condition is specified, it must have a value, or Curator will
  generate an error.
* <<option_max_docs,max_docs>> The maximum number of documents allowed in an
  index before triggering a rollover.  This _must_ be nested under
  `conditions:`. There is no default value.  If this condition is specified, it
  must have a value, or Curator will generate an error.
* <<option_max_size,max_size>> The maximum size the index can be before a rollover is triggered.
  This _must_ be nested under `conditions:`. There is no default value.  If this condition
  is specified, it must have a value, or Curator will generate an error.


=== Optional settings

* <<option_extra_settings,extra_settings>> No default value.  You can add any
    acceptable index settings (not mappings) as nested YAML.  See the
    {ref}/indices-create-index.html[Elasticsearch Create Index API documentation]
    for more information.
* <<option_new_index,new_index>> Specify a new index name.
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_rollover,here>>.



[[shrink]]
== Shrink

[source,yaml]
-------------
action: shrink
description: >-
  Shrink selected indices on the node with the most available space.
  Delete source index after successful shrink, then reroute the shrunk
  index with the provided parameters.
options:
  ignore_empty_list: True
  shrink_node: DETERMINISTIC
  node_filters:
    permit_masters: False
    exclude_nodes: ['not_this_node']
  number_of_shards: 1
  number_of_replicas: 1
  shrink_prefix:
  shrink_suffix: '-shrink'
  delete_after: True
  post_allocation:
    allocation_type: include
    key: node_tag
    value: cold
  wait_for_active_shards: 1
  extra_settings:
    settings:
      index.codec: best_compression
  wait_for_completion: True
  wait_for_rebalance: True
  wait_interval: 9
  max_wait: -1
filters:
  - filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

Shrinking an index is a good way to reduce the total shard count in your cluster.
https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-shrink-index.html#_shrinking_an_index[Several conditions need to be met]
in order for index shrinking to take place:

* The index must be marked as read-only
* A (primary or replica) copy of every shard in the index must be relocated to the same node
* The cluster must have health `green`
* The target index must not exist
* The number of primary shards in the target index must be a factor of the number of primary shards in the source index.
* The source index must have more primary shards than the target index.
* The index must not contain more than 2,147,483,519 documents in total across all shards that will be shrunk into a single shard on the target index as this is the maximum number of docs that can fit into a single shard.
* The node handling the shrink process must have sufficient free disk space to accommodate a second copy of the existing index.

Curator will try to meet these conditions.  If it is unable to meet them all, it will not perform a shrink operation.

This action will shrink indices to the target index, the name of which is the value of
<<option_shrink_prefix,shrink_prefix>> + the source index name + <<option_shrink_suffix,shrink_suffix>>.
The resulting index will have <<option_number_of_shards,number_of_shards>> primary shards, and
<<option_number_of_replicas,number_of_replicas>> replica shards.

The shrinking will take place on the node identified by <<option_shrink_node,shrink_node>>,
unless `DETERMINISTIC` is specified, in which case Curator will evaluate all of
the nodes to determine which one has the most free space.  If multiple indices
are identified for shrinking by the filter block, and `DETERMINISTIC` is specified,
the node selection process will be repeated for each successive index, preventing
all of the space being consumed on a single node.

By default, Curator will delete the source index after a successful shrink. This
can be disabled by setting <<option_delete_after,delete_after>> to `False`.  If the source index,
is not deleted after a successful shrink, Curator will remove the read-only setting and the
shard allocation routing applied to the source index to put it on the shrink node.  Curator will
wait for the shards to stop rerouting before continuing.

The <<option_post_allocation,post_allocation>> option applies to the target index after
the shrink is complete.  If set, this shard allocation routing will be applied (after a
successful shrink) and Curator will wait for all shards to stop rerouting before continuing.

The only <<option_extra_settings,extra_settings>> which are acceptable are `settings` and `aliases`.
Please note that in the example above, while `best_compression` is being applied to the new index,
it will not take effect until new writes are made to the index, such as when
<<forcemerge,force-merging>> the shard to a single segment.

The other options are usually okay to leave at the defaults, but feel free to change them
as needed.

=== Required settings

* <<option_shrink_node,shrink_node>>

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_continue,continue_if_exception>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_copy_aliases,copy_aliases>>
* <<option_delete_after,delete_after>>
* <<option_disable,disable_action>>
* <<option_extra_settings,extra_settings>>
* <<option_node_filters,node_filters>>
* <<option_number_of_shards,number_of_shards>>
* <<option_number_of_replicas,number_of_replicas>>
* <<option_post_allocation,post_allocation>>
* <<option_shrink_prefix,shrink_prefix>>
* <<option_shrink_suffix,shrink_suffix>>
* <<option_timeout_override,timeout_override>>
* <<option_wait_for_active_shards,wait_for_active_shards>>
* <<option_wfc,wait_for_completion>>
* <<option_wait_for_rebalance,wait_for_rebalance>>
* <<option_max_wait,max_wait>>
* <<option_wait_interval,wait_interval>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_shrink,here>>.

[[snapshot]]
== Snapshot

[source,yaml]
-------------
action: snapshot
description: >-
  Snapshot selected indices to 'repository' with the snapshot name or name
  pattern in 'name'.  Use all other options as assigned
options:
  repository: ...
  # Leaving name blank will result in the default 'curator-%Y%m%d%H%M%S'
  name:
  wait_for_completion: True
  max_wait: 3600
  wait_interval: 10
filters:
- filtertype: ...
-------------

NOTE: Empty values and commented lines will result in the default value, if any,
    being selected.  If a setting is set, but not used by a given action, it
    will be ignored.

This action will snapshot indices to the indicated
<<option_repository,repository>>, with a name, or name pattern, as identified by
<<option_name,name>>.

The other options are usually okay to leave at the defaults, but feel free to
read about them and change them accordingly.

=== Required settings

* <<option_repository,repository>>

=== Optional settings

* <<option_search_pattern,search_pattern>>
* <<option_name,name>>
* <<option_ignore,ignore_unavailable>>
* <<option_include_gs,include_global_state>>
* <<option_partial,partial>>
* <<option_wfc,wait_for_completion>>
* <<option_max_wait,max_wait>>
* <<option_wait_interval,wait_interval>>
* <<option_skip_fsck,skip_repo_fs_check>>
* <<option_ignore_empty,ignore_empty_list>>
* <<option_timeout_override,timeout_override>>
* <<option_continue,continue_if_exception>>
* <<option_disable,disable_action>>

TIP: See an example of this action in an <<actionfile,actionfile>>
    <<ex_snapshot,here>>.