Jenkins build module (#745) (#1957)

* Jenkins build module

A module for queuing and deleting jenkins builds.

* CI fixes

* More CI fixes.

* Even more CI fixes

* Fixing symlink

* Update plugins/modules/web_infrastructure/jenkins_build.py

Co-authored-by: Felix Fontein <felix@fontein.de>

* removed ansible meta section

* Added unit tests.

* fix tests

* more test fixes.

* Completed tests.

Mocked jenkins api calls.
Fixed some logging.

* Update plugins/modules/web_infrastructure/jenkins_build.py

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* Update plugins/modules/web_infrastructure/jenkins_build.py

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* Update plugins/modules/web_infrastructure/jenkins_build.py

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* Update plugins/modules/web_infrastructure/jenkins_build.py

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

* Cleaned up default items

And removed supports check mode flag.

* setting name param required

* Update plugins/modules/web_infrastructure/jenkins_build.py

Co-authored-by: Brett Milford <brettmilford@gmail.com>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
(cherry picked from commit ad8aa1b1e6)

Co-authored-by: Brett <19863984+brettmilford@users.noreply.github.com>

plugins/modules/jenkins_build.py

@@ -0,0 +1 @@
+./web_infrastructure/jenkins_build.py

plugins/modules/web_infrastructure/jenkins_build.py

@@ -0,0 +1,243 @@
+#!/usr/bin/python
+#
+# Copyright: (c) Ansible Project
+# 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
+
+DOCUMENTATION = '''
+---
+module: jenkins_build
+short_description: Manage jenkins builds
+version_added: 2.2.0
+description:
+    - Manage Jenkins builds with Jenkins REST API.
+requirements:
+  - "python-jenkins >= 0.4.12"
+author: Brett Milford (@brettmilford)
+options:
+  args:
+    description:
+      - A list of parameters to pass to the build.
+    type: dict
+  name:
+    description:
+      - Name of the Jenkins job to build.
+    required: true
+    type: str
+  build_number:
+    description:
+      - An integer which specifies a build of a job. Is required to remove a build from the queue.
+    type: int
+  password:
+    description:
+      - Password to authenticate with the Jenkins server.
+    type: str
+  state:
+    description:
+      - Attribute that specifies if the build is to be created or deleted.
+    default: present
+    choices: ['present', 'absent']
+    type: str
+  token:
+    description:
+      - API token used to authenticate with the Jenkins server.
+    type: str
+  url:
+    description:
+      - URL of the Jenkins server.
+    default: http://localhost:8080
+    type: str
+  user:
+    description:
+       - User to authenticate with the Jenkins server.
+    type: str
+'''
+
+EXAMPLES = '''
+- name: Create a jenkins build using basic authentication
+  community.general.jenkins_build:
+    name: "test-check"
+    args:
+      cloud: "test"
+      availability_zone: "test_az"
+    user: admin
+    password: asdfg
+    url: http://localhost:8080
+'''
+
+RETURN = '''
+---
+name:
+  description: Name of the jenkins job.
+  returned: success
+  type: str
+  sample: "test-job"
+state:
+  description: State of the jenkins job.
+  returned: success
+  type: str
+  sample: present
+user:
+  description: User used for authentication.
+  returned: success
+  type: str
+  sample: admin
+url:
+  description: Url to connect to the Jenkins server.
+  returned: success
+  type: str
+  sample: https://jenkins.mydomain.com
+build_info:
+  description: Build info of the jenkins job.
+  returned: success
+  type: dict
+'''
+
+import traceback
+from time import sleep
+
+JENKINS_IMP_ERR = None
+try:
+    import jenkins
+    python_jenkins_installed = True
+except ImportError:
+    JENKINS_IMP_ERR = traceback.format_exc()
+    python_jenkins_installed = False
+
+from ansible.module_utils.basic import AnsibleModule, missing_required_lib
+from ansible.module_utils._text import to_native
+
+
+class JenkinsBuild:
+
+    def __init__(self, module):
+        self.module = module
+
+        self.name = module.params.get('name')
+        self.password = module.params.get('password')
+        self.args = module.params.get('args')
+        self.state = module.params.get('state')
+        self.token = module.params.get('token')
+        self.user = module.params.get('user')
+        self.jenkins_url = module.params.get('url')
+        self.build_number = module.params.get('build_number')
+        self.server = self.get_jenkins_connection()
+
+        self.result = {
+            'changed': False,
+            'url': self.jenkins_url,
+            'name': self.name,
+            'user': self.user,
+            'state': self.state,
+        }
+
+        self.EXCL_STATE = "excluded state"
+
+    def get_jenkins_connection(self):
+        try:
+            if (self.user and self.password):
+                return jenkins.Jenkins(self.jenkins_url, self.user, self.password)
+            elif (self.user and self.token):
+                return jenkins.Jenkins(self.jenkins_url, self.user, self.token)
+            elif (self.user and not (self.password or self.token)):
+                return jenkins.Jenkins(self.jenkins_url, self.user)
+            else:
+                return jenkins.Jenkins(self.jenkins_url)
+        except Exception as e:
+            self.module.fail_json(msg='Unable to connect to Jenkins server, %s' % to_native(e))
+
+    def get_next_build(self):
+        try:
+            build_number = self.server.get_job_info(self.name)['nextBuildNumber']
+        except Exception as e:
+            self.module.fail_json(msg='Unable to get job info from Jenkins server, %s' % to_native(e), exception=traceback.format_exc())
+
+        return build_number
+
+    def get_build_status(self):
+        try:
+            response = self.server.get_build_info(self.name, self.build_number)
+            return response
+
+        except Exception as e:
+            self.module.fail_json(msg='Unable to fetch build information, %s' % to_native(e), exception=traceback.format_exc())
+
+    def present_build(self):
+        self.build_number = self.get_next_build()
+
+        try:
+            if self.args is None:
+                self.server.build_job(self.name)
+            else:
+                self.server.build_job(self.name, self.args)
+        except Exception as e:
+            self.module.fail_json(msg='Unable to create build for %s: %s' % (self.jenkins_url, to_native(e)),
+                                  exception=traceback.format_exc())
+
+    def absent_build(self):
+        try:
+            self.server.delete_build(self.name, self.build_number)
+        except Exception as e:
+            self.module.fail_json(msg='Unable to delete build for %s: %s' % (self.jenkins_url, to_native(e)),
+                                  exception=traceback.format_exc())
+
+    def get_result(self):
+        result = self.result
+        build_status = self.get_build_status()
+
+        if build_status['result'] is None:
+            sleep(10)
+            self.get_result()
+        else:
+            if build_status['result'] == "SUCCESS":
+                result['changed'] = True
+                result['build_info'] = build_status
+            else:
+                result['failed'] = True
+                result['build_info'] = build_status
+
+        return result
+
+
+def test_dependencies(module):
+    if not python_jenkins_installed:
+        module.fail_json(
+            msg=missing_required_lib("python-jenkins",
+                                     url="https://python-jenkins.readthedocs.io/en/latest/install.html"),
+            exception=JENKINS_IMP_ERR)
+
+
+def main():
+    module = AnsibleModule(
+        argument_spec=dict(
+            args=dict(type='dict'),
+            build_number=dict(type='int'),
+            name=dict(required=True),
+            password=dict(no_log=True),
+            state=dict(choices=['present', 'absent'], default="present"),
+            token=dict(no_log=True),
+            url=dict(default="http://localhost:8080"),
+            user=dict(),
+        ),
+        mutually_exclusive=[
+            ['password', 'token'],
+        ],
+    )
+
+    test_dependencies(module)
+    jenkins_build = JenkinsBuild(module)
+
+    if module.params.get('state') == "present":
+        jenkins_build.present_build()
+    else:
+        jenkins_build.absent_build()
+
+    sleep(10)
+    result = jenkins_build.get_result()
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()

tests/unit/plugins/modules/web_infrastructure/test_jenkins_build.py

@@ -0,0 +1,110 @@
+# 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
+
+from ansible_collections.community.general.tests.unit.compat import unittest
+from ansible_collections.community.general.tests.unit.compat.mock import patch
+from ansible.module_utils import basic
+from ansible.module_utils._text import to_bytes
+from ansible_collections.community.general.plugins.modules.web_infrastructure import jenkins_build
+
+import json
+
+
+def set_module_args(args):
+    """prepare arguments so that they will be picked up during module creation"""
+    args = json.dumps({'ANSIBLE_MODULE_ARGS': args})
+    basic._ANSIBLE_ARGS = to_bytes(args)
+
+
+class AnsibleExitJson(Exception):
+    """Exception class to be raised by module.exit_json and caught by the test case"""
+    pass
+
+
+class AnsibleFailJson(Exception):
+    """Exception class to be raised by module.fail_json and caught by the test case"""
+    pass
+
+
+def exit_json(*args, **kwargs):
+    """function to patch over exit_json; package return data into an exception"""
+    if 'changed' not in kwargs:
+        kwargs['changed'] = False
+    raise AnsibleExitJson(kwargs)
+
+
+def fail_json(*args, **kwargs):
+    """function to patch over fail_json; package return data into an exception"""
+    kwargs['failed'] = True
+    raise AnsibleFailJson(kwargs)
+
+
+class JenkinsMock():
+
+    def get_job_info(self, name):
+        return {
+            "nextBuildNumber": 1234
+        }
+
+    def get_build_info(self, name, build_number):
+        return {
+            "result": "SUCCESS"
+        }
+
+    def get_build_status(self):
+        pass
+
+    def build_job(self, *args):
+        return None
+
+    def delete_build(self, name, build_number):
+        return None
+
+
+class TestJenkinsBuild(unittest.TestCase):
+
+    def setUp(self):
+        self.mock_module_helper = patch.multiple(basic.AnsibleModule,
+                                                 exit_json=exit_json,
+                                                 fail_json=fail_json)
+        self.mock_module_helper.start()
+        self.addCleanup(self.mock_module_helper.stop)
+
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
+    def test_module_fail_when_required_args_missing(self, test_deps):
+        test_deps.return_value = None
+        with self.assertRaises(AnsibleFailJson):
+            set_module_args({})
+            jenkins_build.main()
+
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.JenkinsBuild.get_jenkins_connection')
+    def test_module_create_build(self, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+
+        with self.assertRaises(AnsibleExitJson):
+            set_module_args({
+                "name": "host-check",
+                "user": "abc",
+                "token": "xyz"
+            })
+            jenkins_build.main()
+
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.web_infrastructure.jenkins_build.JenkinsBuild.get_jenkins_connection')
+    def test_module_delete_build(self, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+
+        with self.assertRaises(AnsibleExitJson):
+            set_module_args({
+                "name": "host-check",
+                "build_number": "1234",
+                "state": "absent",
+                "user": "abc",
+                "token": "xyz"
+            })
+            jenkins_build.main()