[Enhancement] [zos_script] Implement async support for zos_script (#1934)

* adding async support to zos_script

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Update test_zos_script_func.py

* Updating tmp file delete code

* Moving tmp file removal logic to module from action

* Update test_zos_script_func.py

* added change log

* Updating removing tmp file in previous test case

* updating indentation

* Update zos_script.py

* Update changelogs/fragments/1934-zos_script-implemented-async-support

Co-authored-by: Alex Moreno <[email protected]>

---------

Co-authored-by: Alex Moreno <[email protected]>

Author: surendrababuravella

changelogs/fragments/1934-zos_script-implemented-async-support

@@ -0,0 +1,3 @@
+minor_changes:
+  - zos_script - Adds support for running local and remote scripts in asynchronous mode inside playbooks.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1934).

plugins/action/zos_script.py

@@ -24,6 +24,7 @@
 
 class ActionModule(ActionBase):
     def run(self, tmp=None, task_vars=None):
+        self._supports_async = True
         if task_vars is None:
             task_vars = dict()
 
@@ -99,6 +100,8 @@ def run(self, tmp=None, task_vars=None):
             )
             copy_task = self._task.copy()
             copy_task.args = copy_module_args
+            # Making the zos_copy task run synchronously every time.
+            copy_task.async_val = 0
             copy_action = self._shared_loader_obj.action_loader.get(
                 'ibm.ibm_zos_core.zos_copy',
                 task=copy_task,
@@ -133,7 +136,8 @@ def run(self, tmp=None, task_vars=None):
         module_result = self._execute_module(
             module_name='ibm.ibm_zos_core.zos_script',
             module_args=module_args,
-            task_vars=task_vars
+            task_vars=task_vars,
+            wrap_async=self._task.async_val
         )
 
         result = module_result
@@ -143,16 +147,8 @@ def run(self, tmp=None, task_vars=None):
             # restore it to what the user supplied.
             result['cmd'] = user_cmd
 
-        if not remote_src:
-            self._remote_cleanup(tempfile_path)
-
         return result
 
-    def _remote_cleanup(self, tempfile_path):
-        """Removes the temporary file in a managed node created for a local
-        script."""
-        self._connection.exec_command("rm -f {0}".format(tempfile_path))
-
     def _process_boolean(self, arg, default=False):
         try:
             return boolean(arg)

plugins/modules/zos_script.py

@@ -227,6 +227,8 @@
 import os
 import stat
 import shlex
+import os
+from ansible.module_utils._text import to_text
 
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.ibm.ibm_zos_core.plugins.module_utils import (
@@ -340,84 +342,101 @@ def run_module():
     removes = module.params.get('removes')
     remote_src = module.params.get('remote_src')
     script_permissions = None
+    temp_file = script_path if not remote_src else None
 
-    if creates and os.path.exists(creates):
-        result = dict(
-            changed=False,
-            skipped=True,
-            msg='File {0} already exists on the system, skipping script'.format(creates)
-        )
-        module.exit_json(**result)
+    result = dict()
 
-    if removes and not os.path.exists(removes):
-        result = dict(
-            changed=False,
-            skipped=True,
-            msg='File {0} is already missing on the system, skipping script'.format(removes)
-        )
-        module.exit_json(**result)
+    try:
+        if creates and os.path.exists(creates):
+            result = dict(
+                changed=False,
+                skipped=True,
+                msg='File {0} already exists on the system, skipping script'.format(creates)
+            )
+            module.exit_json(**result)
 
-    if chdir and not os.path.exists(chdir):
-        module.fail_json(
-            msg='The given chdir {0} does not exist on the system.'.format(chdir)
-        )
+        if removes and not os.path.exists(removes):
+            result = dict(
+                changed=False,
+                skipped=True,
+                msg='File {0} is already missing on the system, skipping script'.format(removes)
+            )
+            module.exit_json(**result)
 
-    if remote_src and not os.path.exists(script_path):
-        result = dict(
-            changed=False,
-            skipped=True,
-            msg='File {0} does not exist on the system, skipping script'.format(script_path)
-        )
-        module.fail_json(**result)
-
-    # Checking if current user has permission to execute the script.
-    # If not, we'll try to set execution permissions if possible.
-    if not os.access(script_path, os.X_OK):
-        # Adding owner execute permissions to the script.
-        # The module will fail if the Ansible user is not the owner!
-        try:
-            script_permissions = os.lstat(script_path).st_mode
-            os.chmod(
-                script_path,
-                script_permissions | stat.S_IXUSR
+        if chdir and not os.path.exists(chdir):
+            msg = 'The given chdir {0} does not exist on the system.'.format(chdir)
+            raise Exception(msg)
+
+        if remote_src and not os.path.exists(script_path):
+            result = dict(
+                changed=False,
+                skipped=True,
+                msg='File {0} does not exist on the system, skipping script'.format(script_path)
             )
-        except PermissionError:
-            module.fail_json(
-                msg='User running Ansible does not have permission to run script {0}.'.format(
-                    script_path
+            module.fail_json(**result)
+
+        # Checking if current user has permission to execute the script.
+        # If not, we'll try to set execution permissions if possible.
+        if not os.access(script_path, os.X_OK):
+            # Adding owner execute permissions to the script.
+            # The module will fail if the Ansible user is not the owner!
+            try:
+                script_permissions = os.lstat(script_path).st_mode
+                os.chmod(
+                    script_path,
+                    script_permissions | stat.S_IXUSR
                 )
-            )
-
-    if executable:
-        cmd_str = "{0} {1}".format(executable, cmd_str)
+            except PermissionError:
+                msg = 'User running Ansible does not have permission to run script {0}.'.format(script_path)
+                raise PermissionError(msg)
+
+        if executable:
+            cmd_str = "{0} {1}".format(executable, cmd_str)
+
+        cmd_str = cmd_str.strip()
+        script_rc, stdout, stderr = module.run_command(
+            cmd_str,
+            cwd=chdir,
+            errors='replace'
+        )
 
-    cmd_str = cmd_str.strip()
-    script_rc, stdout, stderr = module.run_command(
-        cmd_str,
-        cwd=chdir,
-        errors='replace'
-    )
+        result = dict(
+            changed=True,
+            cmd=module.params.get('cmd'),
+            remote_cmd=cmd_str,
+            rc=script_rc,
+            stdout=stdout,
+            stderr=stderr,
+            stdout_lines=stdout.split('\n'),
+            stderr_lines=stderr.split('\n'),
+        )
 
-    result = dict(
-        changed=True,
-        cmd=module.params.get('cmd'),
-        remote_cmd=cmd_str,
-        rc=script_rc,
-        stdout=stdout,
-        stderr=stderr,
-        stdout_lines=stdout.split('\n'),
-        stderr_lines=stderr.split('\n'),
-    )
+        # Reverting script's permissions when needed.
+        if script_permissions:
+            os.chmod(script_path, script_permissions)
 
-    # Reverting script's permissions when needed.
-    if script_permissions:
-        os.chmod(script_path, script_permissions)
+        if script_rc != 0 or stderr:
+            result['msg'] = 'The script terminated with an error'
+            if temp_file is not None:
+                os.remove(temp_file)
+            module.fail_json(
+                **result
+            )
+    except PermissionError as err:
+        result["failed"] = True
+        result["changed"] = False
+        result["msg"] = ("The script terminated with an error: {0}".format(to_text(err)))
+        module.exit_json(**result)
+    except Exception as err:
+        # if not result["changed"]:
+        result["changed"] = False
+        result["failed"] = True
+        result["msg"] = ("The script terminated with an error: {0}".format(to_text(err)))
+        module.exit_json(**result)
 
-    if script_rc != 0 or stderr:
-        result['msg'] = 'The script terminated with an error'
-        module.fail_json(
-            **result
-        )
+    finally:
+        if temp_file is not None:
+            os.remove(temp_file)
 
     module.exit_json(**result)
 

tests/functional/modules/test_zos_script_func.py

@@ -18,6 +18,9 @@
 import os
 import tempfile
 import pytest
+import yaml
+from shellescape import quote
+import subprocess
 __metaclass__ = type
 
 from ibm_zos_core.tests.helpers.users import ManagedUserType, ManagedUser
@@ -55,6 +58,49 @@
 """
 
 
+PLAYBOOK_ASYNC_TEST = """- hosts: zvm
+  collections:
+    - ibm.ibm_zos_core
+  gather_facts: False
+  environment:
+    _BPXK_AUTOCVT: "ON"
+    ZOAU_HOME: "{0}"
+    PYTHONPATH: "{0}/lib/{2}"
+    LIBPATH: "{0}/lib:{1}/lib:/lib:/usr/lib:."
+    PATH: "{0}/bin:/bin:/usr/lpp/rsusr/ported/bin:/var/bin:/usr/lpp/rsusr/ported/bin:/usr/lpp/java/java180/J8.0_64/bin:{1}/bin:"
+    _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
+    _TAG_REDIR_ERR: "txt"
+    _TAG_REDIR_IN: "txt"
+    _TAG_REDIR_OUT: "txt"
+    LANG: "C"
+
+  tasks:
+    - name: Execute script in async mode.
+      ibm.ibm_zos_core.zos_script:
+        cmd: "{3} FIRST=a SECOND=b"
+      async: 45
+      poll: 0
+      register: job_task
+
+    - name: Query async task.
+      async_status:
+        jid: "{{{{ job_task.ansible_job_id }}}}"
+      register: job_result
+      until: job_result.finished
+      retries: 20
+      delay: 5
+"""
+
+INVENTORY_ASYNC_TEST = """all:
+  hosts:
+    zvm:
+      ansible_host: {0}
+      ansible_ssh_private_key_file: {1}
+      ansible_user: {2}
+      ansible_python_interpreter: {3}"""
+
+
+
 def create_script_content(msg, script_type):
     """Returns a string containing either a valid REXX script or a valid
     Python script. The script will print the given message."""
@@ -424,21 +470,18 @@ def managed_user_run_script(ansible_zos_module):
     hosts = ansible_zos_module
     script_path = '/tmp/zos_script_test_script'
     msg = "Success"
-
     zos_script_result = hosts.all.zos_script(
         cmd=script_path,
         remote_src=True
     )
 
     for result in zos_script_result.contacted.values():
-        print(result)
         assert result.get('changed') is True
         assert result.get('failed', False) is False
         assert result.get('rc') == 0
         assert result.get('stdout', '').strip() == msg
         assert result.get('stderr', '') == ''
 
-
 # Related to issue #1542 in our repository.
 def test_user_run_script_from_another_user(ansible_zos_module, z_python_interpreter):
     hosts = ansible_zos_module
@@ -556,7 +599,70 @@ def test_rexx_script_with_args_remote_src(ansible_zos_module):
             assert args in result.get('remote_cmd')
             assert result.get('stderr', '') == ''
     finally:
-        if os.path.exists(script_path):
-            os.remove(script_path)
         if os.path.exists(local_script):
             os.remove(local_script)
+        hosts.all.file(path=script_path, state="absent")
+
+
+def test_job_script_async(get_config):
+    # Creating temp REXX file used by the playbook.
+    try:
+        rexx_script = REXX_SCRIPT_ARGS
+        script_path = create_local_file(rexx_script, 'rexx')
+
+        # Getting all the info required to run the playbook.
+        path = get_config
+        with open(path, 'r') as file:
+            enviroment = yaml.safe_load(file)
+
+        ssh_key = enviroment["ssh_key"]
+        hosts = enviroment["host"].upper()
+        user = enviroment["user"].upper()
+        python_path = enviroment["python_path"]
+        cut_python_path = python_path[:python_path.find('/bin')].strip()
+        zoau = enviroment["environment"]["ZOAU_ROOT"]
+        python_version = cut_python_path.split('/')[2]
+
+        playbook = tempfile.NamedTemporaryFile(delete=True)
+        inventory = tempfile.NamedTemporaryFile(delete=True)
+
+        os.system("echo {0} > {1}".format(
+            quote(PLAYBOOK_ASYNC_TEST.format(
+                zoau,
+                cut_python_path,
+                python_version,
+                script_path
+            )), 
+            playbook.name
+        ))
+
+        os.system("echo {0} > {1}".format(
+            quote(INVENTORY_ASYNC_TEST.format(
+                hosts,
+                ssh_key,
+                user,
+                python_path
+            )), 
+            inventory.name
+        ))
+
+        command = "ansible-playbook -i {0} {1}".format(
+            inventory.name,
+            playbook.name
+        )
+
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            shell=True,
+            timeout=120,
+            encoding='utf-8'
+        )
+        assert result.returncode == 0
+        assert "ok=2" in result.stdout
+        assert "changed=2" in result.stdout
+        assert result.stderr == ""
+    finally:
+        if os.path.exists(script_path):
+            os.remove(script_path)
+