Add cluster routing functionality

This adds tests and schema validation and documentation (both asciidoc and RST) for this feature.

fixes #446

curator/actions.py

@@ -295,7 +295,7 @@ def __init__(
         #: exception
         self.timeout = '{0}s'.format(timeout)
 
-        if setting is not 'enable':
+        if setting != 'enable':
             raise ValueError(
                 'Invalid value for "setting": {0}.'.format(setting)
             )

curator/cli.py

@@ -77,7 +77,7 @@ def process_action(client, config, **kwargs):
             removes = IndexList(client)
             removes.iterate_filters(config['remove'])
             action_obj.remove(removes)
-    elif action == 'create_index':
+    elif action in [ 'cluster_routing', 'create_index' ]:
         action_obj = action_class(client, **mykwargs)
     elif action == 'delete_snapshots' or action == 'restore':
         logger.debug('Running "{0}"'.format(action))
@@ -123,7 +123,9 @@ def cli(config, dry_run, action_file):
     ### Start working on the actions here ###
     #########################################
     action_config = get_yaml(action_file)
+    logger.debug('PRE-YAY')
     action_dict = validate_actions(action_config)
+    logger.debug('YAY')
     actions = action_dict['actions']
     logger.debug('Full list of actions: {0}'.format(actions))
     action_keys = sorted(list(actions.keys()))

curator/defaults/settings.py

@@ -35,6 +35,10 @@ def date_regex():
     }
 
 # Actions
+
+def cluster_actions():
+    return [ 'cluster_routing' ]
+
 def index_actions():
     return [
         'alias',
@@ -52,7 +56,7 @@ def snapshot_actions():
     return [ 'delete_snapshots', 'restore' ]
 
 def all_actions():
-    return sorted(index_actions() + snapshot_actions())
+    return sorted(cluster_actions() + index_actions() + snapshot_actions())
 
 def index_filtertypes():
     return [

curator/utils.py

@@ -456,7 +456,7 @@ def get_client(**kwargs):
     ``/_cluster/state/metadata`` endpoint.  So long as this endpoint does not
     function in AWS ES, the client will not be able to use
     :class:`curator.indexlist.IndexList`, which is the backbone of Curator 4
-    
+
     Return an :class:`elasticsearch.Elasticsearch` client object using the
     provided parameters. Any of the keyword arguments the
     :class:`elasticsearch.Elasticsearch` client object can receive are valid,
@@ -1124,8 +1124,8 @@ def validate_actions(data):
                     )
             # Add/Remove here
             clean_config[action_id].update(add_remove)
-        elif current_action == 'create_index':
-            # create_index should not have a filters
+        elif current_action in [ 'cluster_routing', 'create_index' ]:
+            # neither cluster_routing nor create_index should have filters
             pass
         else: # Filters key only appears in non-alias actions
             valid_filters = SchemaCheck(

curator/validators/actions.py

@@ -34,8 +34,9 @@ def structure(data, location):
     retval.update(
         { Optional('options', default=settings.default_options()): dict } )
     action = data['action']
-    if action == 'create_index':
-        # The create_index action should not have a 'filters' block
+    if action in [ 'cluster_routing', 'create_index' ]:
+        # Neither the cluster_routing nor create_index actions should have a
+        # 'filters' block
         pass
     elif action == 'alias':
         # The alias action should not have a filters block, but should have

curator/validators/options.py

@@ -86,6 +86,19 @@ def retry_interval():
             )
     }
 
+def routing_type():
+    return { Required('routing_type'): Any('allocation', 'rebalance') }
+
+def cluster_routing_setting():
+    return { Required('setting'): Any('enable') }
+
+def cluster_routing_value():
+    return {
+        Required('value'): Any(
+                'all', 'primaries', 'none', 'new_primaries', 'replicas'
+            )
+    }
+
 def skip_repo_fs_check():
     return { Optional('skip_repo_fs_check', default=False): Boolean() }
 
@@ -107,8 +120,10 @@ def timeout_override(action):
 def value():
     return { Required('value'): str }
 
+
+
 def wait_for_completion(action):
-    if action in ['allocation', 'replicas']:
+    if action in ['allocation', 'cluster_routing', 'replicas']:
         return { Optional('wait_for_completion', default=False): Boolean() }
     elif action in ['restore', 'snapshot']:
         return { Optional('wait_for_completion', default=True): Boolean() }
@@ -127,6 +142,12 @@ def action_specific(action):
             wait_for_completion(action),
         ],
         'close' : [ delete_aliases() ],
+        'cluster_routing' : [
+            routing_type(),
+            cluster_routing_setting(),
+            cluster_routing_value(),
+            wait_for_completion(action),
+        ],
         'create_index' : [
             name(action),
             extra_settings(),

docs/actionclasses.rst

@@ -10,6 +10,7 @@ Action Classes
 * `Alias`_
 * `Allocation`_
 * `Close`_
+* `ClusterRouting`_
 * `DeleteIndices`_
 * `DeleteSnapshots`_
 * `ForceMerge`_
@@ -33,6 +34,11 @@ Close
 .. autoclass:: curator.actions.Close
   :members:
 
+ClusterRouting
+--------------
+.. autoclass:: curator.actions.ClusterRouting
+  :members:
+
 DeleteIndices
 -------------
 .. autoclass:: curator.actions.DeleteIndices

docs/asciidoc/actions.asciidoc

@@ -10,6 +10,7 @@ once created, can only be deleted.
 * <<alias,Alias>>
 * <<allocation,Allocation>>
 * <<close,Close>>
+* <<cluster_routing,Cluster Routing>>
 * <<create_index,Create Index>>
 * <<delete_indices,Delete Indices>>
 * <<delete_snapshots,Delete Snapshots>>
@@ -189,6 +190,62 @@ Optional settings
 TIP: See an example of this action in an <<actionfile,actionfile>>
     <<ex_close,here>>.
 
+[[cluster_routing]]
+== Cluster Routing
+
+[source,text]
+-------------
+action: cluster_routing
+description: "Apply routing rules to the entire cluster"
+options:
+  routing_type:
+  value:
+  setting: enabled
+  wait_for_completion: False
+  timeout_override:
+  continue_if_exception: False
+  disable_action: False
+-------------
+
+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 https://www.elastic.co/guide/en/elasticsearch/reference/current/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.  If
+this option is chosen, it is advisable to use the
+<<option_timeout_override,timeout_override>> option in order to avoid client
+timeouts.
+
+[float]
+Required settings
+~~~~~~~~~~~~~~~~~
+
+* <<option_routing_type,routing_type>> (required)
+* <<option_value,value>> (required)
+* <<option_setting,setting>> Currently must be set to `enabled`.  This setting
+  is a placeholder for potential future expansion.
+
+[float]
+Optional settings
+~~~~~~~~~~~~~~~~~
+
+* <<option_wfc,wait_for_completion>> (has a default value which can optionally
+    be changed)
+* <<option_timeout_override,timeout_override>> (can override the default
+    <<timeout,timeout>>)
+* <<option_continue,continue_if_exception>> (has a default value which can
+    optionally be changed)
+* <<option_disable,disable_action>> (has a default value which can optionally
+    be changed)
+
+TIP: See an example of this action in an <<actionfile,actionfile>>
+    <<ex_cluster_routing,here>>.
 
 [[create_index]]
 == Create Index

docs/asciidoc/examples.asciidoc

@@ -11,6 +11,7 @@ configuration files.
 * <<ex_alias,alias>>
 * <<ex_allocation,allocation>>
 * <<ex_close,close>>
+* <<ex_cluster_routing,cluster_routing>>
 * <<ex_create_index,create_index>>
 * <<ex_delete_indices,delete_indices>>
 * <<ex_delete_snapshots,delete_snapshots>>
@@ -157,6 +158,54 @@ actions:
       exclude:
 -------------
 
+
+[[ex_cluster_routing]]
+== cluster_routing
+
+[source,text]
+-------------
+---
+# Remember, leave a key empty if there is no value.  None will be a string,
+# not a Python "NoneType"
+#
+# Also remember that all examples have 'disable_action' set to True.  If you
+# want to use this action as a template, be sure to set this to False after
+# copying it.
+#
+# This action example has a blank spot at action ID 2.  This is to show that
+# Curator can disable allocation before one or more actions, and then re-enable
+# it afterward.
+actions:
+  1:
+    action: cluster_routing
+    description: >-
+      Disable shard routing for the entire cluster.
+    options:
+      routing_type: allocation
+      value: none
+      setting: enable
+      wait_for_completion: False
+      timeout_override:
+      continue_if_exception: False
+      disable_action: True
+  2:
+    action: (any other action details go here)
+    ...
+  3:
+    action: cluster_routing
+    description: >-
+      Re-enable shard routing for the entire cluster.
+    options:
+      routing_type: allocation
+      value: all
+      setting: enable
+      wait_for_completion: False
+      timeout_override:
+      continue_if_exception: False
+      disable_action: True
+-------------
+
+
 [[ex_create_index]]
 == create_index
 

docs/asciidoc/options.asciidoc

@@ -27,6 +27,8 @@ Options are settings used by <<actions,actions>>.
 * <<option_repository,repository>>
 * <<option_retry_count,retry_count>>
 * <<option_retry_interval,retry_interval>>
+* <<option_routing_type,routing_type>>
+* <<option_setting,setting>>
 * <<option_skip_fsck,skip_repo_fs_check>>
 * <<option_timeout_override,timeout_override>>
 * <<option_value,value>>
@@ -342,6 +344,27 @@ The value of this setting is the number of seconds to delay between retries.
 
 The default for this setting is `120`.
 
+[[option_routing_type]]
+== routing_type
+
+NOTE: This setting is only used by the <<cluster_routing, cluster_routing action>>.
+
+The value of this setting must be either `allocation` or `rebalance`
+
+There is no default value. This setting must be set by the user or an exception
+will be raised, and execution will halt.
+
+[[option_setting]]
+== setting
+
+NOTE: This setting is only used by the <<cluster_routing, cluster_routing action>>.
+
+The value of this must be `enabled` at present.  It is a placeholder for future
+expansion.
+
+There is no default value. This setting must be set by the user or an exception
+will be raised, and execution will halt.
+
 
 [[option_skip_fsck]]
 == skip_repo_fs_check
@@ -394,10 +417,10 @@ from the client-defined default would be desirable.
 == value
 
 NOTE: This setting is required when using the <<allocation,allocation action>>
-    or the <<filtertype_allocated,allocated filtertype>>.
+    or the <<cluster_routing,cluster_routing action>>.
 
-The value of this setting should correspond to a node setting on one or more
-nodes in your cluster.
+For the <<allocation,allocation action>>, the value of this setting should
+correspond to a node setting on one or more nodes in your cluster.
 
 For example, you might have set
 
@@ -412,6 +435,16 @@ the special attribute names `_ip`, `_name`, `_id`, or `_host` for
 <<option_key,key>>, value can match the one of the node ip addresses, names,
 ids, or host names, respectively.
 
+For the <<cluster_routing,cluster_routing action>>, the acceptable values for
+this setting depend on the value of <<option_routing_type,routing_type>>.
+
+Acceptable values when <<option_routing_type,routing_type>> is either
+`allocation` or `rebalance` are `all`, `primaries`, and  `none` (string, not
+`NoneType`).
+
+If `routing_type` is `allocation`, this can also be ``new_primaries``. If
+`routing_type is `rebalance`, then the value can also be `replicas`.
+
 There is no default value. This setting must be set by the user or an exception
 will be raised, and execution will halt.