Improvements to the jenkins_build module and new jenkins_build_info module (#7204)

* Add detach option so the task doesn't wait until the Jenkins job is finished

* Add new time_between_checks to be able to configure the sleep time between requests

* New jenkins_build_info to get information about a specific build

* Add version_added to the new module

* Add changelog fragment for jenkins_build changes

* Fix tests that required the python-jenkins module

* Remove tests that failed

Doesn't really make sense to test that with a mock

* Fix pep8 error

* Update maintainers for the jenkins_build and jenkins_build_info modules

* Improve format and add link to PR

* Move version_added documentation to the right file

* Fix incorrect examples

* Improve text format

* Fix incorrect code style

* Fix incorrect YAML for documentation

* Add version_added documentation to the new options

.github/BOTMETA.yml

@@ -669,7 +669,9 @@ files:
     labels: jboss
     maintainers: $team_jboss jhoekx
   $modules/jenkins_build.py:
-    maintainers: brettmilford unnecessary-username
+    maintainers: brettmilford unnecessary-username juanmcasanova
+  $modules/jenkins_build_info.py:
+    maintainers: juanmcasanova
   $modules/jenkins_job.py:
     maintainers: sermilrod
   $modules/jenkins_job_info.py:

changelogs/fragments/improvements-to-jenkins-build-module.yml

@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - jenkins_build - add new ``detach`` option, which allows the module to exit successfully as long as the build is created (default functionality is still waiting for the build to end before exiting) (https://github.com/ansible-collections/community.general/pull/7204).
+  - jenkins_build - add new ``time_between_checks`` option, which allows to configure the wait time between requests to the Jenkins server (https://github.com/ansible-collections/community.general/pull/7204).

plugins/modules/jenkins_build.py

@@ -20,6 +20,7 @@ requirements:
 author:
   - Brett Milford (@brettmilford)
   - Tong He (@unnecessary-username)
+  - Juan Casanova (@juanmcasanova)
 extends_documentation_fragment:
   - community.general.attributes
 attributes:
@@ -65,6 +66,19 @@ options:
     description:
        - User to authenticate with the Jenkins server.
     type: str
+  detach:
+    description:
+      - Enable detached mode to not wait for the build end.
+    default: false
+    type: bool
+    version_added: 7.4.0
+  time_between_checks:
+    description:
+      - Time in seconds to wait between requests to the Jenkins server.
+      - This times must be higher than the configured quiet time for the job.
+    default: 10
+    type: int
+    version_added: 7.4.0
 '''
 
 EXAMPLES = '''
@@ -152,6 +166,8 @@ class JenkinsBuild:
         self.user = module.params.get('user')
         self.jenkins_url = module.params.get('url')
         self.build_number = module.params.get('build_number')
+        self.detach = module.params.get('detach')
+        self.time_between_checks = module.params.get('time_between_checks')
         self.server = self.get_jenkins_connection()
 
         self.result = {
@@ -235,7 +251,14 @@ class JenkinsBuild:
         build_status = self.get_build_status()
 
         if build_status['result'] is None:
-            sleep(10)
+            # If detached mode is active mark as success, we wouldn't be able to get here if it didn't exist
+            if self.detach:
+                result['changed'] = True
+                result['build_info'] = build_status
+
+                return result
+
+            sleep(self.time_between_checks)
             self.get_result()
         else:
             if self.state == "stopped" and build_status['result'] == "ABORTED":
@@ -273,6 +296,8 @@ def main():
             token=dict(no_log=True),
             url=dict(default="http://localhost:8080"),
             user=dict(),
+            detach=dict(type='bool', default=False),
+            time_between_checks=dict(type='int', default=10),
         ),
         mutually_exclusive=[['password', 'token']],
         required_if=[['state', 'absent', ['build_number'], True], ['state', 'stopped', ['build_number'], True]],
@@ -288,7 +313,7 @@ def main():
     else:
         jenkins_build.absent_build()
 
-    sleep(10)
+    sleep(jenkins_build.time_between_checks)
     result = jenkins_build.get_result()
     module.exit_json(**result)
 

plugins/modules/jenkins_build_info.py

@@ -0,0 +1,210 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: jenkins_build_info
+short_description: Get information about Jenkins builds
+version_added: 7.4.0
+description:
+    - Get information about Jenkins builds with Jenkins REST API.
+requirements:
+  - "python-jenkins >= 0.4.12"
+author:
+  - Juan Casanova (@juanmcasanova)
+extends_documentation_fragment:
+  - community.general.attributes
+  - community.general.attributes.info_module
+options:
+  name:
+    description:
+      - Name of the Jenkins job to which the build belongs.
+    required: true
+    type: str
+  build_number:
+    description:
+      - An integer which specifies a build of a job.
+      - If not specified the last build information will be returned.
+    type: int
+  password:
+    description:
+      - Password to authenticate with the Jenkins server.
+    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: Get information about a jenkins build using basic authentication
+  community.general.jenkins_build_info:
+    name: "test-check"
+    build_number: 1
+    user: admin
+    password: asdfg
+    url: http://localhost:8080
+
+- name: Get information about a jenkins build anonymously
+  community.general.jenkins_build_info:
+    name: "stop-check"
+    build_number: 3
+    url: http://localhost:8080
+
+- name: Get information about a jenkins build using token authentication
+  community.general.jenkins_build_info:
+    name: "delete-experiment"
+    build_number: 30
+    user: Jenkins
+    token: abcdefghijklmnopqrstuvwxyz123456
+    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
+
+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.common.text.converters import to_native
+
+
+class JenkinsBuildInfo:
+
+    def __init__(self, module):
+        self.module = module
+
+        self.name = module.params.get('name')
+        self.password = module.params.get('password')
+        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,
+        }
+
+    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_build_status(self):
+        try:
+            if self.build_number is None:
+                job_info = self.server.get_job_info(self.name)
+                self.build_number = job_info['lastBuild']['number']
+
+            return self.server.get_build_info(self.name, self.build_number)
+        except jenkins.JenkinsException as e:
+            response = {}
+            response["result"] = "ABSENT"
+            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 get_result(self):
+        result = self.result
+        build_status = self.get_build_status()
+
+        if build_status['result'] == "ABSENT":
+            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(
+            build_number=dict(type='int'),
+            name=dict(required=True),
+            password=dict(no_log=True),
+            token=dict(no_log=True),
+            url=dict(default="http://localhost:8080"),
+            user=dict(),
+        ),
+        mutually_exclusive=[['password', 'token']],
+        supports_check_mode=True,
+    )
+
+    test_dependencies(module)
+    jenkins_build_info = JenkinsBuildInfo(module)
+
+    result = jenkins_build_info.get_result()
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()

tests/unit/plugins/modules/test_jenkins_build.py

@@ -75,6 +75,11 @@ class JenkinsMock():
     def get_build_info(self, name, build_number):
         if name == "host-delete":
             raise jenkins.JenkinsException("job {0} number {1} does not exist".format(name, build_number))
+        elif name == "create-detached":
+            return {
+                "building": True,
+                "result": None
+            }
         return {
             "building": True,
             "result": "SUCCESS"
@@ -222,3 +227,38 @@ class TestJenkinsBuild(unittest.TestCase):
                 "token": "xyz"
             })
             jenkins_build.main()
+
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build.JenkinsBuild.get_jenkins_connection')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build.JenkinsBuild.get_build_status')
+    def test_module_create_build_without_detach(self, build_status, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+        build_status.return_value = JenkinsBuildMock().get_build_status()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "create-detached",
+                "user": "abc",
+                "token": "xyz"
+            })
+            jenkins_build.main()
+
+        self.assertFalse(return_json.exception.args[0]['changed'])
+
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build.JenkinsBuild.get_jenkins_connection')
+    def test_module_create_build_detached(self, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "create-detached",
+                "user": "abc",
+                "token": "xyz",
+                "detach": True
+            })
+            jenkins_build.main()
+
+        self.assertTrue(return_json.exception.args[0]['changed'])

tests/unit/plugins/modules/test_jenkins_build_info.py

@@ -0,0 +1,180 @@
+# Copyright (c) Ansible project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+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.common.text.converters import to_bytes
+from ansible_collections.community.general.plugins.modules import jenkins_build_info
+
+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 jenkins:
+    class JenkinsException(Exception):
+        pass
+
+
+class JenkinsBuildMock():
+    def __init__(self, name, build_number=None):
+        self.name = name
+        self.build_number = build_number
+
+    def get_build_status(self):
+        try:
+            instance = JenkinsMock()
+            response = JenkinsMock.get_build_info(instance, self.name, self.build_number)
+            return response
+        except jenkins.JenkinsException:
+            response = {}
+            response["result"] = "ABSENT"
+            return response
+        except Exception as e:
+            fail_json(msg='Unable to fetch build information, {0}'.format(e))
+
+
+class JenkinsMock():
+
+    def get_build_info(self, name, build_number):
+        if name == "job-absent":
+            raise jenkins.JenkinsException()
+
+        return {
+            "result": "SUCCESS",
+            "build_info": {}
+        }
+
+    def get_job_info(self, name):
+        if name == "job-absent":
+            raise jenkins.JenkinsException()
+
+        return {
+            "lastBuild": {
+                "number": 123
+            }
+        }
+
+
+class TestJenkinsBuildInfo(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.jenkins_build_info.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_info.main()
+
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.JenkinsBuildInfo.get_jenkins_connection')
+    def test_module_get_build_info(self, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "job-present",
+                "user": "abc",
+                "token": "xyz",
+                "build_number": 30
+            })
+            jenkins_build_info.main()
+
+        self.assertFalse(return_json.exception.args[0]["changed"])
+
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.JenkinsBuildInfo.get_jenkins_connection')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.JenkinsBuildInfo.get_build_status')
+    def test_module_get_build_info_if_build_does_not_exist(self, build_status, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+        build_status.return_value = JenkinsBuildMock("job-absent", 30).get_build_status()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "job-absent",
+                "user": "abc",
+                "token": "xyz",
+                "build_number": 30
+            })
+            jenkins_build_info.main()
+
+        self.assertFalse(return_json.exception.args[0]['changed'])
+        self.assertTrue(return_json.exception.args[0]['failed'])
+        self.assertEquals("ABSENT", return_json.exception.args[0]['build_info']['result'])
+
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.JenkinsBuildInfo.get_jenkins_connection')
+    def test_module_get_build_info_get_last_build(self, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "job-present",
+                "user": "abc",
+                "token": "xyz"
+            })
+            jenkins_build_info.main()
+
+        self.assertFalse(return_json.exception.args[0]['changed'])
+        self.assertEquals("SUCCESS", return_json.exception.args[0]['build_info']['result'])
+
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.test_dependencies')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.JenkinsBuildInfo.get_jenkins_connection')
+    @patch('ansible_collections.community.general.plugins.modules.jenkins_build_info.JenkinsBuildInfo.get_build_status')
+    def test_module_get_build_info_if_job_does_not_exist(self, build_status, jenkins_connection, test_deps):
+        test_deps.return_value = None
+        jenkins_connection.return_value = JenkinsMock()
+        build_status.return_value = JenkinsBuildMock("job-absent").get_build_status()
+
+        with self.assertRaises(AnsibleExitJson) as return_json:
+            set_module_args({
+                "name": "job-absent",
+                "user": "abc",
+                "token": "xyz"
+            })
+            jenkins_build_info.main()
+
+        self.assertFalse(return_json.exception.args[0]['changed'])
+        self.assertTrue(return_json.exception.args[0]['failed'])
+        self.assertEquals("ABSENT", return_json.exception.args[0]['build_info']['result'])