Add ara_record module to record key/value pairs

ara_record is a new Ansible module specific to ARA.
It is meant for users to register any key value pair throughout
their playbook execution so that it is available through CLI or the
web interface.

Change-Id: I480011a4037ecdc561183b7b7cb334011d1f4b10

ara/plugins/actions/ara_record.py

@@ -0,0 +1,133 @@
+#   Copyright Red Hat, Inc. All Rights Reserved.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License"); you may
+#   not use this file except in compliance with the License. You may obtain
+#   a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#   License for the specific language governing permissions and limitations
+#   under the License.
+#
+
+import json
+import os
+
+from ansible.plugins.action import ActionBase
+
+try:
+    from ara import app, models
+    from ara.models import db
+    HAS_ARA = True
+except ImportError:
+    HAS_ARA = False
+
+DOCUMENTATION = '''
+---
+module: ara_record
+short_description: Ansible module to record persistent data with ARA.
+version_added: "2.0"
+author: "RDO Community <rdo-list@redhat.com>"
+description:
+    - Ansible module to record persistent data with ARA.
+options:
+    key:
+        description:
+            - Name of the key to write data to
+        required: true
+    value:
+        description:
+            - Value of the key written to
+        required: true
+
+requirements:
+    - "python >= 2.6"
+    - "ara >= 0.10.0"
+'''
+
+EXAMPLES = '''
+# Write static data
+- ara_record:
+    key: "foo"
+    value: "bar"
+
+# Write dynamic data
+- shell: cd dev && git rev-parse HEAD
+  register: git_version
+  delegate_to: localhost
+
+- ara_record:
+    key: "git_version"
+    value: "{{ git_version.stdout }}"
+'''
+
+
+class ActionModule(ActionBase):
+    ''' Record persistent data as key/value pairs in ARA '''
+
+    TRANSFERS_FILES = False
+    VALID_ARGS = frozenset(('key', 'value'))
+
+    def create_or_update_key(self, playbook_id, key, value):
+        try:
+            data = (models.Data.query
+                    .filter_by(key=key)
+                    .filter_by(playbook_id=playbook_id)
+                    .one())
+            data.value = value
+        except models.NoResultFound:
+            data = models.Data(playbook_id=playbook_id,
+                               key=key,
+                               value=value)
+        db.session.add(data)
+        db.session.commit()
+
+        return data
+
+    def run(self, tmp=None, task_vars=None):
+        if task_vars is None:
+            task_vars = dict()
+
+        if not HAS_ARA:
+            result = {
+                "failed": True,
+                "msg": "ARA is required to run this module."
+            }
+            return result
+
+        for arg in self._task.args:
+            if arg not in self.VALID_ARGS:
+                result = {
+                    "failed": True,
+                    "msg": "'{0}' is not a valid option.".format(arg)
+                }
+                return result
+
+        result = super(ActionModule, self).run(tmp, task_vars)
+
+        key = self._task.args.get('key', None)
+        value = self._task.args.get('value', None)
+
+        required = ['key', 'value']
+        for parameter in required:
+            if not self._task.args.get(parameter):
+                result['failed'] = True
+                result['msg'] = "{} parameter is required".format(parameter)
+                return result
+
+        # Retrieve the persisted playbook_id from tmpfile
+        tmpfile = os.path.join(app.config['ARA_TMP_DIR'], 'ara.json')
+        with open(tmpfile) as file:
+            data = json.load(file)
+        playbook_id = data['playbook']['id']
+
+        try:
+            self.create_or_update_key(playbook_id, key, value)
+            result['msg'] = "Data recorded in ARA for this playbook."
+        except Exception as e:
+            result['failed'] = True
+            result['msg'] = "Data not recorded in ARA: {0}".format(str(e))
+        return result

ara/plugins/callbacks/log_ara.py

@@ -263,6 +263,16 @@ class CallbackModule(CallbackBase):
         file_ = self.get_or_create_file(path)
         file_.is_playbook = True
 
+        # We need to persist the playbook id so it can be used by the modules
+        data = {
+            'playbook': {
+                'id': self.playbook.id
+            }
+        }
+        tmpfile = os.path.join(app.config['ARA_TMP_DIR'], 'ara.json')
+        with open(tmpfile, 'w') as file:
+            file.write(json.dumps(data))
+
     def v2_playbook_on_play_start(self, play):
         self.close_task()
         self.close_play()

ara/plugins/modules/ara_record.py

@@ -0,0 +1,60 @@
+#   Copyright Red Hat, Inc. All Rights Reserved.
+#
+#   Licensed under the Apache License, Version 2.0 (the "License"); you may
+#   not use this file except in compliance with the License. You may obtain
+#   a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#   License for the specific language governing permissions and limitations
+#   under the License.
+#
+
+# This file is purposefully left empty due to an Ansible issue
+# Details at: https://github.com/ansible/ansible/pull/18208
+
+# TODO: Remove this file and update the documentation when the issue is fixed,
+# released and present in all supported versions.
+
+DOCUMENTATION = '''
+---
+module: ara_record
+short_description: Ansible module to record data with ARA
+version_added: "2.0"
+author: "RDO Community <rdo-list@redhat.com>"
+description:
+    - Ansible module to record data with ARA. This module should always be
+      executed wherever the playbook is run from.
+options:
+    key:
+        description:
+            - Name of the key to write data to
+        required: true
+    value:
+        description:
+            - Value of the key written to
+        required: true
+
+requirements:
+    - "python >= 2.6"
+    - "ara >= 0.10.0"
+'''
+
+EXAMPLES = '''
+# Write static data
+- ara_record:
+    key: "foo"
+    value: "bar"
+
+# Write dynamic data
+- shell: cd dev && git rev-parse HEAD
+  register: git_version
+  delegate_to: localhost
+
+- ara_record:
+    key: "git_version"
+    value: "{{ git_version.stdout }}"
+'''