From 01864514c2e3e1d738e13b5c6cf65e19b1e7b4cf Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Mon, 11 Sep 2023 06:00:57 +0200 Subject: [PATCH] [PR #7204/afeeb89a backport][stable-7] Improvements to the jenkins_build module and new jenkins_build_info module (#7234) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 (cherry picked from commit afeeb89af6ad977ea16606f37b915e5b35ef0a7a) Co-authored-by: Juan Manuel Casanova González --- .github/BOTMETA.yml | 4 +- .../improvements-to-jenkins-build-module.yml | 4 + plugins/modules/jenkins_build.py | 29 ++- plugins/modules/jenkins_build_info.py | 210 ++++++++++++++++++ .../plugins/modules/test_jenkins_build.py | 40 ++++ .../modules/test_jenkins_build_info.py | 180 +++++++++++++++ 6 files changed, 464 insertions(+), 3 deletions(-) create mode 100644 changelogs/fragments/improvements-to-jenkins-build-module.yml create mode 100644 plugins/modules/jenkins_build_info.py create mode 100644 tests/unit/plugins/modules/test_jenkins_build_info.py diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index ee7cc20fc1..9b4cc5ad85 100644 --- a/.github/BOTMETA.yml +++ b/.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: diff --git a/changelogs/fragments/improvements-to-jenkins-build-module.yml b/changelogs/fragments/improvements-to-jenkins-build-module.yml new file mode 100644 index 0000000000..60abd62fea --- /dev/null +++ b/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). diff --git a/plugins/modules/jenkins_build.py b/plugins/modules/jenkins_build.py index bca2a02b4a..6d830849e7 100644 --- a/plugins/modules/jenkins_build.py +++ b/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) diff --git a/plugins/modules/jenkins_build_info.py b/plugins/modules/jenkins_build_info.py new file mode 100644 index 0000000000..eae6eb9374 --- /dev/null +++ b/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() diff --git a/tests/unit/plugins/modules/test_jenkins_build.py b/tests/unit/plugins/modules/test_jenkins_build.py index 44c6307ac9..d9013a0181 100644 --- a/tests/unit/plugins/modules/test_jenkins_build.py +++ b/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']) diff --git a/tests/unit/plugins/modules/test_jenkins_build_info.py b/tests/unit/plugins/modules/test_jenkins_build_info.py new file mode 100644 index 0000000000..58a2d65b3d --- /dev/null +++ b/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'])