Add a step to patch instance parameters in runtime (#341)

Closes #253

Sometimes we want to change some `box.cfg` parameters in runtime only.

Now, it's possible to do like this:

```yaml
- name: Set replication_connect_quorum to zero
  hosts: "*storage*"
  become: true
  gather_facts: no
  roles:
    - tarantool.cartridge
  vars:
    cartridge_scenario:
      - patch_instance_in_runtime
    cartridge_runtime_params:
      replication_connect_quorum: 0
```

Author: hackallcode

.github/helpers/count_molecule_matrix.py

@@ -54,6 +54,7 @@ def main(event_name, repo_owner, review_state, ref):
         ce_matrix.append(get_ce_params(molecule_scenario='eval'))
         ce_matrix.append(get_ce_params(molecule_scenario='needs_restart'))
         ce_matrix.append(get_ce_params(molecule_scenario='package_name'))
+        ce_matrix.append(get_ce_params(molecule_scenario='patch_instance'))
         ce_matrix.append(get_ce_params(molecule_scenario='rolling_update'))
         ce_matrix.append(get_ce_params(molecule_scenario='start_stop'))
         ce_matrix.append(get_ce_params(molecule_scenario='tasks_from'))

CHANGELOG.md

@@ -23,6 +23,7 @@ README.md to use the newest tag with new release
 - availability to upload ZIP configs to TDG
 - `cartridge_not_save_cookie_in_app_config` variable that allows to disable persisting cluster
   cookie in the application configuration file
+- `patch_instance_in_runtime` step to update instance parameters in runtime
 
 ## [1.9.0] - 2021-04-30
 

defaults/main.yml

@@ -96,6 +96,7 @@ cartridge_keep_num_latest_dists: 2
 
 cartridge_defaults: {}
 config: null
+cartridge_runtime_params: null
 zone: null
 
 restarted: null

doc/scenario.md

@@ -54,6 +54,7 @@ There are additional steps that are not included in the default scenario, but ca
 - [stop_instance](#stop_instance)
 - [start_instance](#start_instance)
 - [restart_instance_force](#restart_instance_force)
+- [patch_instance_in_runtime](#patch_instance_in_runtime)
 
 To replace the steps of the role with your own or add new steps, you should use `cartridge_custom_steps_dir`
 or `cartridge_custom_steps` options (see [examples](#examples)).
@@ -824,3 +825,22 @@ Restart and enable instance systemd service without any conditions.
 Input facts (set by role):
 
 - `instance_info` - information for a current instance ([more details here](#role-facts-descriptions)).
+
+### patch_instance_in_runtime
+
+Patch dynamic (see [parameters](https://www.tarantool.io/en/doc/latest/reference/configuration/#configuration-parameters)
+with `Dynamic: yes`) instance parameters in runtime only
+(now it's possible to change only `box` config parameters).
+If the none-dynamic parameter is specified,
+nothing will be changed, and an error will be returned.
+
+**Note** that memory size can be only increased in runtime.
+
+Input facts (set by role):
+
+- `instance_info` - information for a current instance ([more details here](#role-facts-descriptions)).
+
+Input facts (set by config):
+
+- `cartridge_runtime_params` - new instance parameters ([more details here](/doc/instances.md));
+- `expelled` - indicates if instance must be expelled from topology.

doc/variables.md

@@ -78,11 +78,13 @@ For more details see [scenario documentation](/doc/scenario.md).
 
 ## Instances configuration
 
+* `cartridge_defaults` (`dict`, default: `{}`): default configuration
+  parameters values for instances;
 * `config` (`dict`, required): [instance configuration](/doc/instances.md);
 * `zone` (`string`): instance zone (available since
   [Cartridge 2.4.0](https://github.com/tarantool/cartridge/releases/tag/2.4.0));
-* `cartridge_defaults` (`dict`, default: `{}`): default configuration
-  parameters values for instances;
+* `cartridge_runtime_params` (`dict`): [instance configuration](/doc/instances.md)
+  parameters to patch in runtime;
 * `restarted` (`boolean`): flag indicates if instance should be
   restarted or not (if this flag isn't specified, instance will be restarted if
   it's needed to apply configuration changes);

library/cartridge_get_cached_facts.py

@@ -17,6 +17,7 @@
         'cartridge_app_user',
         'cartridge_auth',
         'cartridge_bootstrap_vshard',
+        'cartridge_runtime_params',
         'cartridge_cluster_cookie',
         'cartridge_not_save_cookie_in_app_config',
         'cartridge_conf_dir',

library/cartridge_instance.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python
+
+from copy import deepcopy
+
+from ansible.module_utils.helpers import Helpers as helpers
+
+argument_spec = {
+    'console_sock': {'required': True, 'type': 'str'},
+    'instance_config': {'required': True, 'type': 'dict'},
+    'cartridge_defaults': {'required': False, 'type': 'dict', 'default': {}},
+    'strict_mode': {'required': False, 'type': 'bool', 'default': False},
+}
+
+
+def change_memory_size(control_console, param_name, new_value):
+    if new_value is None:
+        return False, None
+
+    increase_memory_func_body = '''
+        local param_name, new_memory_size = ...
+        local ok, err = pcall(box.cfg, { [param_name] = new_memory_size })
+        if not ok then
+            if tostring(err):find("cannot decrease memory size at runtime") == nil then
+                return nil, string.format('failed to set %s: %s', param_name, err)
+            end
+        end
+        return ok
+    '''
+    return control_console.eval_res_err(increase_memory_func_body, param_name, new_value)
+
+
+def change_dynamic_params(control_console, old_box_config, new_config, strict_mode=False):
+    memory_sizes_to_change = {}
+    box_params_to_change = {}
+    incorrect_memory_changes = []
+    non_dynamic_params = []
+
+    for param_name, new_value in new_config.items():
+        old_box_value = old_box_config.get(param_name)
+
+        if param_name in helpers.MEMORY_SIZE_BOX_CFG_PARAMS:
+            if new_value > old_box_value:
+                memory_sizes_to_change.update({param_name: new_value})
+            else:
+                incorrect_memory_changes.append((param_name, old_box_value, new_value))
+
+        elif param_name in helpers.DYNAMIC_BOX_CFG_PARAMS:
+            if new_value != old_box_value:
+                box_params_to_change.update({param_name: new_value})
+
+        else:
+            non_dynamic_params.append(param_name)
+
+    if strict_mode:
+        messages = []
+        if incorrect_memory_changes:
+            messages.append('impossible to decrease memory sizes in runtime (%s)' % ', '.join(
+                map(lambda change_info: "'%s' from '%s' to '%s'" % change_info, incorrect_memory_changes)
+            ))
+        if non_dynamic_params:
+            messages.append("impossible to change '%s' in runtime" % ', '.join(non_dynamic_params))
+        if messages:
+            return None, "Impossible to patch instance config: %s" % '; '.join(messages)
+
+    memory_changed = False
+    for param_name, new_value in memory_sizes_to_change.items():
+        changed, err = change_memory_size(control_console, param_name, new_value)
+        if err is not None:
+            return None, 'Failed to change memory size in runtime: %s' % err
+        if changed:
+            memory_changed = True
+
+    box_changed = False
+    if box_params_to_change:
+        update_box_cfg_func_body = '''
+            box.cfg(...)
+            return box.cfg
+        '''
+        updated_config, _ = control_console.eval_res_err(update_box_cfg_func_body, box_params_to_change)
+        box_changed = old_box_config != updated_config
+
+    return memory_changed or box_changed, None
+
+
+def configure_box_cfg_params(console_sock, instance_config, defaults=None, strict_mode=False):
+    control_console, err = helpers.get_control_console_if_started(console_sock, strict_mode)
+    if err is not None:
+        return None, err
+    if not control_console:
+        return False, None
+
+    if not helpers.box_cfg_was_called(control_console):
+        if strict_mode:
+            return None, "Impossible to patch instance config: 'box.cfg' wasn't called"
+        return False, None
+
+    old_box_config = helpers.get_box_cfg(control_console)
+    new_config = deepcopy(defaults or {})
+    new_config.update(instance_config)
+
+    return change_dynamic_params(control_console, old_box_config, new_config, strict_mode)
+
+
+def patch_instance_in_runtime(params):
+    console_sock = params['console_sock']
+    instance_config = params['instance_config']
+    cartridge_defaults = params['cartridge_defaults']
+    strict_mode = params['strict_mode']
+
+    changed, error = configure_box_cfg_params(console_sock, instance_config, cartridge_defaults, strict_mode)
+    if error is not None:
+        return helpers.ModuleRes(failed=True, msg=error)
+    return helpers.ModuleRes(changed=changed)
+
+
+if __name__ == '__main__':
+    helpers.execute_module(argument_spec, patch_instance_in_runtime)

library/cartridge_patch_instance_in_runtime.py

@@ -93,6 +93,7 @@
     'cartridge_app_name': str,
     'cartridge_cluster_cookie': str,
     'cartridge_not_save_cookie_in_app_config': bool,
+    'cartridge_runtime_params': dict,
     'cartridge_defaults': dict,
     'cartridge_bootstrap_vshard': bool,
     'cartridge_wait_buckets_discovery': bool,

library/cartridge_validate_config.py

@@ -275,6 +275,13 @@ def __init__(self, code, message):
         super(CartridgeException, self).__init__(message)
         self.code = code
 
+    def is_instance_not_started_error(self):
+        return self.code in [
+            CartridgeErrorCodes.SOCKET_NOT_FOUND,
+            CartridgeErrorCodes.FAILED_TO_CONNECT_TO_SOCKET,
+            CartridgeErrorCodes.INSTANCE_IS_NOT_STARTED_YET
+        ]
+
 
 class Console:
     def __init__(self, socket_path):
@@ -437,6 +444,22 @@ def get_control_console(socket_path):
     return Console(socket_path)
 
 
+def get_control_console_if_started(console_sock, strict_mode=False):
+    if not os.path.exists(console_sock):
+        if strict_mode:
+            return None, "console socket '%s' doesn't exists" % console_sock
+        return None, None
+
+    try:
+        return get_control_console(console_sock), None
+    except CartridgeException as e:
+        if not strict_mode and e.is_instance_not_started_error():
+            # Impossible to connect to socket
+            return None, None
+
+        return None, str(e)
+
+
 def is_expelled(host_vars):
     return host_vars.get('expelled') is True
 
@@ -597,6 +620,7 @@ class Helpers:
     warn = staticmethod(warn)
     execute_module = staticmethod(execute_module)
     get_control_console = staticmethod(get_control_console)
+    get_control_console_if_started = staticmethod(get_control_console_if_started)
     is_expelled = staticmethod(is_expelled)
     is_stateboard = staticmethod(is_stateboard)
     get_instance_id = staticmethod(get_instance_id)