diff --git a/plugins/modules/jenkins_build.py b/plugins/modules/jenkins_build.py new file mode 120000 index 0000000000..13e660e7b0 --- /dev/null +++ b/plugins/modules/jenkins_build.py @@ -0,0 +1 @@ +./web_infrastructure/jenkins_build.py \ No newline at end of file diff --git a/plugins/modules/web_infrastructure/jenkins_build.py b/plugins/modules/web_infrastructure/jenkins_build.py new file mode 100644 index 0000000000..7f1d32b602 --- /dev/null +++ b/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() diff --git a/tests/unit/plugins/modules/web_infrastructure/test_jenkins_build.py b/tests/unit/plugins/modules/web_infrastructure/test_jenkins_build.py new file mode 100644 index 0000000000..d0bbafcc91 --- /dev/null +++ b/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()