Merge pull request ansible#9896 from sean-m-sullivan/approval_node

Add workflow approval and node wait modules

SUMMARY
Please see ansible#9878 this is a clean PR after redoing my fork.
Add a module to find a workflow approval node and approve or deny it, based on Issue ansible#8013.
Add a module to wait for a specific workflow node to complete and return information on it.
Both of these are based on tests I have been creating for testing workflows.
Scenario
Launch workflow
Wait for A node in the workflow to finish, compare output to expected output.
If it matches, approve the approval node, otherwise deny the approval node.
Workflow completes.
Even used in concert I've added the wait feature to both of these so a user can wait on either to appear.
This does require a workflow to use unique names on the job nodes they are waiting on, As the job # is created on the fly, it would be difficult for user to specify, A future update could explore searching for a specific identifier among a workflow template and then finding that job created by that identifier.
Currently without the modules this depends on generous use of the uri module, with until and retry coupled together.
ISSUE TYPE
Feature Pull Request

COMPONENT NAME
awx-collection
AWX VERSION
19.0.0

Reviewed-by: Bianca Henderson <[email protected]>

awx_collection/plugins/module_utils/tower_api.py

@@ -743,3 +743,37 @@ def wait_on_url(self, url, object_name, object_type, timeout=30, interval=10):
     def wait_output(self, response):
         for k in ('id', 'status', 'elapsed', 'started', 'finished'):
             self.json_output[k] = response['json'].get(k)
+
+    def wait_on_workflow_node_url(self, url, object_name, object_type, timeout=30, interval=10, **kwargs):
+        # Grab our start time to compare against for the timeout
+        start = time.time()
+        result = self.get_endpoint(url, **kwargs)
+
+        while result["json"]["count"] == 0:
+            # If we are past our time out fail with a message
+            if timeout and timeout < time.time() - start:
+                # Account for Legacy messages
+                self.json_output["msg"] = "Monitoring of {0} - {1} aborted due to timeout, {2}".format(object_type, object_name, url)
+                self.wait_output(result)
+                self.fail_json(**self.json_output)
+
+            # Put the process to sleep for our interval
+            time.sleep(interval)
+            result = self.get_endpoint(url, **kwargs)
+
+        if object_type == "Workflow Approval":
+            # Approval jobs have no elapsed time so return
+            return result["json"]["results"][0]
+        else:
+            # Removed time so far from timeout.
+            revised_timeout = timeout - (time.time() - start)
+            # Now that Job has been found, wait for it to finish
+            result = self.wait_on_url(
+                url=result["json"]["results"][0]["related"]["job"],
+                object_name=object_name,
+                object_type=object_type,
+                timeout=revised_timeout,
+                interval=interval,
+            )
+        self.json_output["job_data"] = result["json"]
+        return result

awx_collection/plugins/modules/tower_workflow_approval.py

@@ -0,0 +1,125 @@
+#!/usr/bin/python
+# coding: utf-8 -*-
+
+# (c) 2021, Sean Sullivan
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {
+    "metadata_version": "1.1",
+    "status": ["preview"],
+    "supported_by": "community",
+}
+
+
+DOCUMENTATION = """
+---
+module: tower_workflow_approval
+author: "Sean Sullivan (@sean-m-sullivan)"
+short_description: Approve an approval node in a workflow job.
+description:
+    - Approve an approval node in a workflow job. See
+      U(https://www.ansible.com/tower) for an overview.
+options:
+    workflow_job_id:
+      description:
+        - ID of the workflow job to monitor for approval.
+      required: True
+      type: int
+    name:
+      description:
+        - Name of the Approval node to approve or deny.
+      required: True
+      type: str
+    action:
+      description:
+        - Type of action to take.
+      choices: ["approve", "deny"]
+      default: "approve"
+      type: str
+    interval:
+      description:
+        - The interval in sections, to request an update from Tower.
+      required: False
+      default: 1
+      type: float
+    timeout:
+      description:
+        - Maximum time in seconds to wait for a workflow job to to reach approval node.
+      default: 10
+      type: int
+extends_documentation_fragment: awx.awx.auth
+"""
+
+
+EXAMPLES = """
+- name: Launch a workflow with a timeout of 10 seconds
+  tower_workflow_launch:
+    workflow_template: "Test Workflow"
+    wait: False
+  register: workflow
+
+- name: Wait for approval node to activate and approve
+  tower_workflow_approval:
+    workflow_job_id: "{{ workflow.id }}"
+    name: Approve Me
+    interval: 10
+    timeout: 20
+    action: deny
+"""
+
+RETURN = """
+
+"""
+
+
+from ..module_utils.tower_api import TowerAPIModule
+
+
+def main():
+    # Any additional arguments that are not fields of the item can be added here
+    argument_spec = dict(
+        workflow_job_id=dict(type="int", required=True),
+        name=dict(required=True),
+        action=dict(choices=["approve", "deny"], default="approve"),
+        timeout=dict(type="int", default=10),
+        interval=dict(type="float", default=1),
+    )
+
+    # Create a module for ourselves
+    module = TowerAPIModule(argument_spec=argument_spec)
+
+    # Extract our parameters
+    workflow_job_id = module.params.get("workflow_job_id")
+    name = module.params.get("name")
+    action = module.params.get("action")
+    timeout = module.params.get("timeout")
+    interval = module.params.get("interval")
+
+    # Attempt to look up workflow job based on the provided id
+    approval_job = module.wait_on_workflow_node_url(
+        url="workflow_jobs/{0}/workflow_nodes/".format(workflow_job_id),
+        object_name=name,
+        object_type="Workflow Approval",
+        timeout=timeout,
+        interval=interval,
+        **{
+            "data": {
+                "job__name": name,
+            }
+        }
+    )
+    response = module.post_endpoint("{0}{1}".format(approval_job["related"]["job"], action))
+    if response["status_code"] == 204:
+        module.json_output["changed"] = True
+
+    # Attempt to look up jobs based on the status
+    module.exit_json(**module.json_output)
+
+
+if __name__ == "__main__":
+    main()

awx_collection/plugins/modules/tower_workflow_node_wait.py

@@ -0,0 +1,115 @@
+#!/usr/bin/python
+# coding: utf-8 -*-
+
+# (c) 2021, Sean Sullivan
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {
+    "metadata_version": "1.1",
+    "status": ["preview"],
+    "supported_by": "community",
+}
+
+
+DOCUMENTATION = """
+---
+module: tower_workflow_node_wait
+author: "Sean Sullivan (@sean-m-sullivan)"
+short_description: Approve an approval node in a workflow job.
+description:
+    - Approve an approval node in a workflow job. See
+      U(https://www.ansible.com/tower) for an overview.
+options:
+    workflow_job_id:
+      description:
+        - ID of the workflow job to monitor for node.
+      required: True
+      type: int
+    name:
+      description:
+        - Name of the workflow node to wait on.
+      required: True
+      type: str
+    interval:
+      description:
+        - The interval in sections, to request an update from Tower.
+      required: False
+      default: 1
+      type: float
+    timeout:
+      description:
+        - Maximum time in seconds to wait for a workflow job to to reach approval node.
+      default: 10
+      type: int
+extends_documentation_fragment: awx.awx.auth
+"""
+
+
+EXAMPLES = """
+- name: Launch a workflow with a timeout of 10 seconds
+  tower_workflow_launch:
+    workflow_template: "Test Workflow"
+    wait: False
+  register: workflow
+
+- name: Wait for a workflow node to finish
+  tower_workflow_node_wait:
+    workflow_job_id: "{{ workflow.id }}"
+    name: Approval Data Step
+    timeout: 120
+"""
+
+RETURN = """
+
+"""
+
+
+from ..module_utils.tower_api import TowerAPIModule
+import time
+
+
+def main():
+    # Any additional arguments that are not fields of the item can be added here
+    argument_spec = dict(
+        workflow_job_id=dict(type="int", required=True),
+        name=dict(required=True),
+        timeout=dict(type="int", default=10),
+        interval=dict(type="float", default=1),
+    )
+
+    # Create a module for ourselves
+    module = TowerAPIModule(argument_spec=argument_spec)
+
+    # Extract our parameters
+    workflow_job_id = module.params.get("workflow_job_id")
+    name = module.params.get("name")
+    timeout = module.params.get("timeout")
+    interval = module.params.get("interval")
+
+    node_url = "workflow_jobs/{0}/workflow_nodes/?job__name={1}".format(workflow_job_id, name)
+    # Attempt to look up workflow job node based on the provided id
+
+    result = module.wait_on_workflow_node_url(
+        url="workflow_jobs/{0}/workflow_nodes/".format(workflow_job_id),
+        object_name=name,
+        object_type="Workflow Node",
+        timeout=timeout,
+        interval=interval,
+        **{
+            "data": {
+                "job__name": name,
+            }
+        }
+    )
+
+    # Attempt to look up jobs based on the status
+    module.exit_json(**module.json_output)
+
+
+if __name__ == "__main__":
+    main()

awx_collection/test/awx/test_completeness.py

@@ -36,6 +36,7 @@
     'tower_receive',
     'tower_send',
     'tower_workflow_launch',
+    'tower_workflow_node_wait',
     'tower_job_cancel',
     'tower_workflow_template',
     'tower_ad_hoc_command_wait',
@@ -64,16 +65,17 @@
     'tower_ad_hoc_command': ['interval', 'timeout', 'wait'],
     # tower_group parameters to perserve hosts and children.
     'tower_group': ['preserve_existing_children', 'preserve_existing_hosts'],
+    # tower_workflow_approval parameters that do not apply when approving an approval node.
+    'tower_workflow_approval': ['action', 'interval', 'timeout', 'workflow_job_id'],
 }
 
 # When this tool was created we were not feature complete. Adding something in here indicates a module
 # that needs to be developed. If the module is found on the file system it will auto-detect that the
 # work is being done and will bypass this check. At some point this module should be removed from this list.
-needs_development = [
-    'tower_workflow_approval',
-]
+needs_development = ['tower_inventory_script']
 needs_param_development = {
     'tower_host': ['instance_id'],
+    'tower_workflow_approval': ['description', 'execution_environment'],
 }
 # -----------------------------------------------------------------------------------------------------------