adds feature to all modules to be run locally (#18763)

* adds new error AnsibleModuleExit to handle module returns
* adds new action plugin network for attaching connection to network modules
* adds new shared module local to receive connection
* splits out function to update task_args with common updates

This commit provides a mechansim for running local modules that require
a connection object for interative commands tyically implemented for
network devices.  It provides a way to locally import modules (post fork)
and run them using exception handling to exit.

lib/ansible/errors/__init__.py

@@ -196,3 +196,8 @@ class AnsibleUndefinedVariable(AnsibleRuntimeError):
 class AnsibleFileNotFound(AnsibleRuntimeError):
     ''' a file missing failure '''
     pass
+
+class AnsibleModuleExit(Exception):
+    ''' local module exit '''
+    def __init__(self, result):
+        self.result = result

lib/ansible/module_utils/local.py

@@ -0,0 +1,78 @@
+#
+# This code is part of Ansible, but is an independent component.
+# This particular file snippet, and this file snippet only, is BSD licensed.
+# Modules you write using this snippet, which is embedded dynamically by Ansible
+# still belong to the author of the module, and may assign their own license
+# to the complete work.
+#
+# (c) 2016 Red Hat Inc.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+#    * Redistributions of source code must retain the above copyright
+#      notice, this list of conditions and the following disclaimer.
+#    * Redistributions in binary form must reproduce the above copyright notice,
+#      this list of conditions and the following disclaimer in the documentation
+#      and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+import json
+
+import ansible.module_utils.basic
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.basic import remove_values
+
+from ansible.errors import AnsibleModuleExit
+
+_ANSIBLE_CONNECTION = None
+
+def _modify_module(task_args, connection):
+    params = {'ANSIBLE_MODULE_ARGS': task_args}
+    ansible.module_utils.basic._ANSIBLE_ARGS = json.dumps(params)
+
+    global _ANSIBLE_CONNECTION
+    _ANSIBLE_CONNECTION = connection
+
+class LocalAnsibleModule(AnsibleModule):
+
+    @property
+    def connection(self):
+        return _ANSIBLE_CONNECTION
+
+    def exec_command(self, args, check_rc=False):
+        '''
+        Execute a command, returns rc, stdout, and stderr.
+        '''
+        rc, out, err = self.connection.exec_command(args)
+        if check_rc and rc != 0:
+            self.fail_json(msg='command %s failed' % args, rc=rc, stderr=err, stdout=out)
+        return rc, out, err
+
+    def exit_json(self, **kwargs):
+        ''' return from the module, without error '''
+        if not 'changed' in kwargs:
+            kwargs['changed'] = False
+        if 'invocation' not in kwargs:
+            kwargs['invocation'] = {'module_args': self.params}
+        kwargs = remove_values(kwargs, self.no_log_values)
+        raise AnsibleModuleExit(kwargs)
+
+    def fail_json(self, **kwargs):
+        ''' return from the module, with an error message '''
+        assert 'msg' in kwargs, "implementation error -- msg to explain the error is required"
+        kwargs['failed'] = True
+        if 'invocation' not in kwargs:
+            kwargs['invocation'] = {'module_args': self.params}
+        kwargs = remove_values(kwargs, self.no_log_values)
+        raise AnsibleModuleExit(kwargs)

lib/ansible/plugins/action/__init__.py

@@ -517,19 +517,7 @@ class ActionBase(with_metaclass(ABCMeta, object)):
             data = re.sub(r'^((\r)?\n)?BECOME-SUCCESS.*(\r)?\n', '', data)
         return data
 
-    def _execute_module(self, module_name=None, module_args=None, tmp=None, task_vars=None, persist_files=False, delete_remote_tmp=True):
+    def _update_module_args(self, module_args, task_vars):
-        '''
-        Transfer and run a module along with its arguments.
-        '''
-        if task_vars is None:
-            task_vars = dict()
-
-        # if a module name was not specified for this execution, use
-        # the action from the task
-        if module_name is None:
-            module_name = self._task.action
-        if module_args is None:
-            module_args = self._task.args
 
         # set check mode in the module arguments, if required
         if self._play_context.check_mode:
@@ -539,9 +527,6 @@ class ActionBase(with_metaclass(ABCMeta, object)):
         else:
             module_args['_ansible_check_mode'] = False
 
-        # Get the connection user for permission checks
-        remote_user = task_vars.get('ansible_ssh_user') or self._play_context.remote_user
-
         # set no log in the module arguments, if required
         module_args['_ansible_no_log'] = self._play_context.no_log or C.DEFAULT_NO_TARGET_SYSLOG
 
@@ -558,7 +543,7 @@ class ActionBase(with_metaclass(ABCMeta, object)):
         module_args['_ansible_version'] = __version__
 
         # give the module information about its name
-        module_args['_ansible_module_name'] = module_name
+        module_args['_ansible_module_name'] = self._task.action
 
         # set the syslog facility to be used in the module
         module_args['_ansible_syslog_facility'] = task_vars.get('ansible_syslog_facility', C.DEFAULT_SYSLOG_FACILITY)
@@ -566,6 +551,25 @@ class ActionBase(with_metaclass(ABCMeta, object)):
         # let module know about filesystems that selinux treats specially
         module_args['_ansible_selinux_special_fs'] = C.DEFAULT_SELINUX_SPECIAL_FS
 
+    def _execute_module(self, module_name=None, module_args=None, tmp=None, task_vars=None, persist_files=False, delete_remote_tmp=True):
+        '''
+        Transfer and run a module along with its arguments.
+        '''
+        if task_vars is None:
+            task_vars = dict()
+
+        # if a module name was not specified for this execution, use
+        # the action from the task
+        if module_name is None:
+            module_name = self._task.action
+        if module_args is None:
+            module_args = self._task.args
+
+        # Get the connection user for permission checks
+        remote_user = task_vars.get('ansible_ssh_user') or self._play_context.remote_user
+
+        self._update_module_args(module_args, task_vars)
+
         (module_style, shebang, module_data, module_path) = self._configure_module(module_name=module_name, module_args=module_args, task_vars=task_vars)
         display.vvv("Using module file %s" % module_path)
         if not shebang and module_style != 'binary':

lib/ansible/plugins/action/network.py

@@ -0,0 +1,65 @@
+#
+# (c) 2016 Red Hat Inc.
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import datetime
+
+from ansible.plugins.action import ActionBase, display
+from ansible.module_utils.local import _modify_module
+from ansible.errors import AnsibleModuleExit
+
+class ActionModule(ActionBase):
+
+    def run(self, tmp=None, task_vars=None):
+        result = super(ActionModule, self).run(tmp, task_vars)
+        del result['invocation']['module_args']
+
+        self._update_module_args(self._task.args, task_vars)
+
+        try:
+            _modify_module(self._task.args, self._connection)
+            path = self._shared_loader_obj.module_loader.find_plugin(self._task.action)
+            pkg = '.'.join(['ansible', 'modules', self._task.action])
+            module = self._shared_loader_obj.module_loader._load_module_source(pkg, path)
+            start_time = datetime.datetime.now()
+            module.main()
+
+        except AnsibleModuleExit as exc:
+            result.update(exc.result)
+            for field in ('_ansible_notify',):
+                if field in result:
+                    results.pop(field)
+
+        except Exception as exc:
+            if display.verbosity > 2:
+                raise
+            result.update(dict(failed=True, msg=str(exc)))
+
+        end_time = datetime.datetime.now()
+        delta = end_time - start_time
+
+        result.update({
+            'start': str(start_time),
+            'end': str(end_time),
+            'delta': str(delta)
+        })
+
+        return result
+