From d7e5e85f3ef883cc837b229b3fa558e6b612fa63 Mon Sep 17 00:00:00 2001 From: CWollinger Date: Tue, 26 Apr 2022 07:58:32 +0200 Subject: [PATCH] New module alerta_customer (#4554) * first draft of alerta_customer * Update BOTMETA.yml * update after review * fix pagination and state description * remove whitespace --- .github/BOTMETA.yml | 2 + plugins/modules/alerta_customer.py | 1 + plugins/modules/monitoring/alerta_customer.py | 199 ++++++++++++++ .../targets/alerta_customer/aliases | 2 + .../targets/alerta_customer/defaults/main.yml | 4 + .../targets/alerta_customer/tasks/main.yml | 151 +++++++++++ .../monitoring/test_alerta_customer.py | 248 ++++++++++++++++++ 7 files changed, 607 insertions(+) create mode 120000 plugins/modules/alerta_customer.py create mode 100644 plugins/modules/monitoring/alerta_customer.py create mode 100644 tests/integration/targets/alerta_customer/aliases create mode 100644 tests/integration/targets/alerta_customer/defaults/main.yml create mode 100644 tests/integration/targets/alerta_customer/tasks/main.yml create mode 100644 tests/unit/plugins/modules/monitoring/test_alerta_customer.py diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 741e2e0ad4..1153162ced 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -562,6 +562,8 @@ files: maintainers: phumpal labels: airbrake_deployment ignore: bpennypacker + $modules/monitoring/alerta_customer.py: + maintainers: cwollinger $modules/monitoring/bigpanda.py: maintainers: hkariti $modules/monitoring/circonus_annotation.py: diff --git a/plugins/modules/alerta_customer.py b/plugins/modules/alerta_customer.py new file mode 120000 index 0000000000..4f4859d33d --- /dev/null +++ b/plugins/modules/alerta_customer.py @@ -0,0 +1 @@ +./monitoring/alerta_customer.py \ No newline at end of file diff --git a/plugins/modules/monitoring/alerta_customer.py b/plugins/modules/monitoring/alerta_customer.py new file mode 100644 index 0000000000..27b0abe1a9 --- /dev/null +++ b/plugins/modules/monitoring/alerta_customer.py @@ -0,0 +1,199 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# Copyright: (c) 2022, Christian Wollinger <@cwollinger> +# 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: alerta_customer +short_description: Manage customers in Alerta +version_added: 4.8.0 +description: + - Create or delete customers in Alerta with the REST API. +author: Christian Wollinger (@cwollinger) +seealso: + - name: API documentation + description: Documentation for Alerta API + link: https://docs.alerta.io/api/reference.html#customers +options: + customer: + description: + - Name of the customer. + required: true + type: str + match: + description: + - The matching logged in user for the customer. + required: true + type: str + alerta_url: + description: + - The Alerta API endpoint. + required: true + type: str + api_username: + description: + - The username for the API using basic auth. + type: str + api_password: + description: + - The password for the API using basic auth. + type: str + api_key: + description: + - The access token for the API. + type: str + state: + description: + - Whether the customer should exist or not. + - Both I(customer) and I(match) identify a customer that should be added or removed. + type: str + choices: [ absent, present ] + default: present +''' + +EXAMPLES = """ +- name: Create customer + community.general.alerta_customer: + alerta_url: https://alerta.example.com + api_username: admin@example.com + api_password: password + customer: Developer + match: dev@example.com + +- name: Delete customer + community.general.alerta_customer: + alerta_url: https://alerta.example.com + api_username: admin@example.com + api_password: password + customer: Developer + match: dev@example.com + state: absent +""" + +RETURN = """ +msg: + description: + - Success or failure message. + returned: always + type: str + sample: Customer customer1 created +response: + description: + - The response from the API. + returned: always + type: dict +""" + +from ansible.module_utils.urls import fetch_url, basic_auth_header +from ansible.module_utils.basic import AnsibleModule + + +class AlertaInterface(object): + + def __init__(self, module): + self.module = module + self.state = module.params['state'] + self.customer = module.params['customer'] + self.match = module.params['match'] + self.alerta_url = module.params['alerta_url'] + self.headers = {"Content-Type": "application/json"} + + if module.params.get('api_key', None): + self.headers["Authorization"] = "Key %s" % module.params['api_key'] + else: + self.headers["Authorization"] = basic_auth_header(module.params['api_username'], module.params['api_password']) + + def send_request(self, url, data=None, method="GET"): + response, info = fetch_url(self.module, url, data=data, headers=self.headers, method=method) + + status_code = info["status"] + if status_code == 401: + self.module.fail_json(failed=True, response=info, msg="Unauthorized to request '%s' on '%s'" % (method, url)) + elif status_code == 403: + self.module.fail_json(failed=True, response=info, msg="Permission Denied for '%s' on '%s'" % (method, url)) + elif status_code == 404: + self.module.fail_json(failed=True, response=info, msg="Not found for request '%s' on '%s'" % (method, url)) + elif status_code in (200, 201): + return self.module.from_json(response.read()) + self.module.fail_json(failed=True, response=info, msg="Alerta API error with HTTP %d for %s" % (status_code, url)) + + def get_customers(self): + url = "%s/api/customers" % self.alerta_url + response = self.send_request(url) + pages = response["pages"] + if pages > 1: + for page in range(2, pages + 1): + page_url = url + '?page=' + str(page) + new_results = self.send_request(page_url) + response.update(new_results) + return response + + def create_customer(self): + url = "%s/api/customer" % self.alerta_url + + payload = { + 'customer': self.customer, + 'match': self.match, + } + + payload = self.module.jsonify(payload) + response = self.send_request(url, payload, 'POST') + return response + + def delete_customer(self, id): + url = "%s/api/customer/%s" % (self.alerta_url, id) + + response = self.send_request(url, None, 'DELETE') + return response + + def find_customer_id(self, customer): + for i in customer['customers']: + if self.customer == i['customer'] and self.match == i['match']: + return i['id'] + return None + + +def main(): + module = AnsibleModule( + argument_spec=dict( + state=dict(choices=['present', 'absent'], default='present'), + customer=dict(type='str', required=True), + match=dict(type='str', required=True), + alerta_url=dict(type='str', required=True), + api_username=dict(type='str'), + api_password=dict(type='str', no_log=True), + api_key=dict(type='str', no_log=True), + ), + required_together=[['api_username', 'api_password']], + mutually_exclusive=[['api_username', 'api_key']], + supports_check_mode=True + ) + + alerta_iface = AlertaInterface(module) + + if alerta_iface.state == 'present': + response = alerta_iface.get_customers() + if alerta_iface.find_customer_id(response): + module.exit_json(changed=False, response=response, msg="Customer %s already exists" % alerta_iface.customer) + else: + if not module.check_mode: + response = alerta_iface.create_customer() + module.exit_json(changed=True, response=response, msg="Customer %s created" % alerta_iface.customer) + else: + response = alerta_iface.get_customers() + id = alerta_iface.find_customer_id(response) + if id: + if not module.check_mode: + alerta_iface.delete_customer(id) + module.exit_json(changed=True, response=response, msg="Customer %s with id %s deleted" % (alerta_iface.customer, id)) + else: + module.exit_json(changed=False, response=response, msg="Customer %s does not exists" % alerta_iface.customer) + + +if __name__ == "__main__": + main() diff --git a/tests/integration/targets/alerta_customer/aliases b/tests/integration/targets/alerta_customer/aliases new file mode 100644 index 0000000000..268da2c702 --- /dev/null +++ b/tests/integration/targets/alerta_customer/aliases @@ -0,0 +1,2 @@ +shippable/posix/group1 +disabled diff --git a/tests/integration/targets/alerta_customer/defaults/main.yml b/tests/integration/targets/alerta_customer/defaults/main.yml new file mode 100644 index 0000000000..f07352a92d --- /dev/null +++ b/tests/integration/targets/alerta_customer/defaults/main.yml @@ -0,0 +1,4 @@ +alerta_url: http://localhost:8080/ +alerta_user: admin@example.com +alerta_password: password +alerta_key: demo-key diff --git a/tests/integration/targets/alerta_customer/tasks/main.yml b/tests/integration/targets/alerta_customer/tasks/main.yml new file mode 100644 index 0000000000..8e80e5a323 --- /dev/null +++ b/tests/integration/targets/alerta_customer/tasks/main.yml @@ -0,0 +1,151 @@ +#################################################################### +# WARNING: These are designed specifically for Ansible tests # +# and should not be used as examples of how to write Ansible roles # +#################################################################### + +- name: Create customer (check mode) + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_username: "{{ alerta_user }}" + api_password: "{{ alerta_password }}" + customer: customer1 + match: admin@admin.admin + check_mode: true + register: result + +- name: Check result (check mode) + assert: + that: + - result is changed + +- name: Create customer + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_username: "{{ alerta_user }}" + api_password: "{{ alerta_password }}" + customer: customer1 + match: admin@admin.admin + register: result + +- name: Check customer creation + assert: + that: + - result is changed + +- name: Test customer creation idempotency + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_username: "{{ alerta_user }}" + api_password: "{{ alerta_password }}" + customer: customer1 + match: admin@admin.admin + register: result + +- name: Check customer creation idempotency + assert: + that: + - result is not changed + +- name: Delete customer (check mode) + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_username: "{{ alerta_user }}" + api_password: "{{ alerta_password }}" + customer: customer1 + match: admin@admin.admin + state: absent + check_mode: true + register: result + +- name: Check customer deletion (check mode) + assert: + that: + - result is changed + +- name: Delete customer + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_username: "{{ alerta_user }}" + api_password: "{{ alerta_password }}" + customer: customer1 + match: admin@admin.admin + state: absent + register: result + +- name: Check customer deletion + assert: + that: + - result is changed + +- name: Test customer deletion idempotency + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_username: "{{ alerta_user }}" + api_password: "{{ alerta_password }}" + customer: customer1 + match: admin@admin.admin + state: absent + register: result + +- name: Check customer deletion idempotency + assert: + that: + - result is not changed + +- name: Delete non-existing customer (check mode) + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_username: "{{ alerta_user }}" + api_password: "{{ alerta_password }}" + customer: customer1 + match: admin@admin.admin + state: absent + check_mode: true + register: result + +- name: Check non-existing customer deletion (check mode) + assert: + that: + - result is not changed + +- name: Create customer with api key + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_key: "{{ alerta_key }}" + customer: customer1 + match: admin@admin.admin + register: result + +- name: Check customer creation with api key + assert: + that: + - result is changed + +- name: Delete customer with api key + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_key: "{{ alerta_key }}" + customer: customer1 + match: admin@admin.admin + state: absent + register: result + +- name: Check customer deletion with api key + assert: + that: + - result is changed + +- name: Use wrong api key + alerta_customer: + alerta_url: "{{ alerta_url }}" + api_key: wrong_key + customer: customer1 + match: admin@admin.admin + register: result + ignore_errors: true + +- name: Check customer creation with api key + assert: + that: + - result is not changed + - result is failed diff --git a/tests/unit/plugins/modules/monitoring/test_alerta_customer.py b/tests/unit/plugins/modules/monitoring/test_alerta_customer.py new file mode 100644 index 0000000000..8ad46db363 --- /dev/null +++ b/tests/unit/plugins/modules/monitoring/test_alerta_customer.py @@ -0,0 +1,248 @@ +# 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 + +import json +import pytest +from ansible_collections.community.general.tests.unit.compat.mock import Mock, patch +from ansible_collections.community.general.plugins.modules.monitoring import alerta_customer +from ansible_collections.community.general.tests.unit.plugins.modules.utils import AnsibleExitJson, AnsibleFailJson, ModuleTestCase, set_module_args + + +class MockedReponse(object): + def __init__(self, data): + self.data = data + + def read(self): + return self.data + + +def customer_response_page1(): + server_response = json.dumps({"customers": [ + { + "customer": "admin", + "href": "http://localhost:8080/api/customer/d89664a7-9c87-4ab9-8be8-830e7e5f0616", + "id": "d89664a7-9c87-4ab9-8be8-830e7e5f0616", + "match": "admin@example.com" + }, + { + "customer": "Developer", + "href": "http://localhost:8080/api/customer/188ed093-84cc-4f46-bf80-4c9127180d9c", + "id": "188ed093-84cc-4f46-bf80-4c9127180d9c", + "match": "dev@example.com" + }], + "more": True, + "page": 1, + "pageSize": 50, + "pages": 1, + "status": "ok", + "total": 2}) + return (MockedReponse(server_response), {"status": 200}) + + +def customer_response_page2(): + server_response = json.dumps({"customers": [ + { + "customer": "admin", + "href": "http://localhost:8080/api/customer/d89664a7-9c87-4ab9-8be8-830e7e5f0616", + "id": "d89664a7-9c87-4ab9-8be8-830e7e5f0616", + "match": "admin@example.com" + }, + { + "customer": "Developer", + "href": "http://localhost:8080/api/customer/188ed093-84cc-4f46-bf80-4c9127180d9c", + "id": "188ed093-84cc-4f46-bf80-4c9127180d9c", + "match": "dev@example.com" + }], + "more": True, + "page": 2, + "pageSize": 50, + "pages": 2, + "status": "ok", + "total": 52}) + return (MockedReponse(server_response), {"status": 200}) + + +class TestAlertaCustomerModule(ModuleTestCase): + + def setUp(self): + super(TestAlertaCustomerModule, self).setUp() + self.module = alerta_customer + + def tearDown(self): + super(TestAlertaCustomerModule, self).tearDown() + + @pytest.fixture + def fetch_url_mock(self, mocker): + return mocker.patch() + + def test_without_parameters(self): + """Failure if no parameters set""" + with self.assertRaises(AnsibleFailJson): + set_module_args({}) + self.module.main() + + def test_without_content(self): + """Failure if customer and match are missing""" + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "admin@example.com", + 'api_password': "password" + }) + with self.assertRaises(AnsibleFailJson): + self.module.main() + + def test_successful_existing_customer_creation(self): + """Test the customer creation (already exists).""" + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "admin@example.com", + 'api_password': "password", + 'customer': 'Developer', + 'match': 'dev@example.com' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = customer_response_page1() + with self.assertRaises(AnsibleExitJson): + self.module.main() + self.assertTrue(fetch_url_mock.call_count, 1) + + def test_successful_customer_creation(self): + """Test the customer creation.""" + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "admin@example.com", + 'api_password': "password", + 'customer': 'Developer', + 'match': 'dev2@example.com' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = customer_response_page1() + with self.assertRaises(AnsibleExitJson): + self.module.main() + + self.assertTrue(fetch_url_mock.call_count, 1) + call_data = json.loads(fetch_url_mock.call_args[1]['data']) + assert call_data['match'] == "dev2@example.com" + assert call_data['customer'] == "Developer" + + def test_successful_customer_creation_key(self): + """Test the customer creation using api_key.""" + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_key': "demo-key", + 'customer': 'Developer', + 'match': 'dev2@example.com' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = customer_response_page1() + with self.assertRaises(AnsibleExitJson): + self.module.main() + + self.assertTrue(fetch_url_mock.call_count, 1) + call_data = json.loads(fetch_url_mock.call_args[1]['data']) + assert call_data['match'] == "dev2@example.com" + assert call_data['customer'] == "Developer" + + def test_failed_not_found(self): + """Test failure with wrong URL.""" + + set_module_args({ + 'alerta_url': "http://localhost:8080/s", + 'api_username': "admin@example.com", + 'api_password': "password", + 'customer': 'Developer', + 'match': 'dev@example.com' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = (None, {"status": 404, 'msg': 'Not found for request GET on http://localhost:8080/a/api/customers'}) + with self.assertRaises(AnsibleFailJson): + self.module.main() + + def test_failed_forbidden(self): + """Test failure with wrong user.""" + + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "dev@example.com", + 'api_password': "password", + 'customer': 'Developer', + 'match': 'dev@example.com' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = (None, {"status": 403, 'msg': 'Permission Denied for GET on http://localhost:8080/api/customers'}) + with self.assertRaises(AnsibleFailJson): + self.module.main() + + def test_failed_unauthorized(self): + """Test failure with wrong username or password.""" + + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "admin@example.com", + 'api_password': "password_wrong", + 'customer': 'Developer', + 'match': 'dev@example.com' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = (None, {"status": 401, 'msg': 'Unauthorized to request GET on http://localhost:8080/api/customers'}) + with self.assertRaises(AnsibleFailJson): + self.module.main() + + def test_successful_customer_deletion(self): + """Test the customer deletion.""" + + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "admin@example.com", + 'api_password': "password", + 'customer': 'Developer', + 'match': 'dev@example.com', + 'state': 'absent' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = customer_response_page1() + with self.assertRaises(AnsibleExitJson): + self.module.main() + + def test_successful_customer_deletion_page2(self): + """Test the customer deletion on the second page.""" + + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "admin@example.com", + 'api_password': "password", + 'customer': 'Developer', + 'match': 'dev@example.com', + 'state': 'absent' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = customer_response_page2() + with self.assertRaises(AnsibleExitJson): + self.module.main() + + def test_successful_nonexisting_customer_deletion(self): + """Test the customer deletion (non existing).""" + + set_module_args({ + 'alerta_url': "http://localhost:8080", + 'api_username': "admin@example.com", + 'api_password': "password", + 'customer': 'Billing', + 'match': 'dev@example.com', + 'state': 'absent' + }) + + with patch.object(alerta_customer, "fetch_url") as fetch_url_mock: + fetch_url_mock.return_value = customer_response_page1() + with self.assertRaises(AnsibleExitJson): + self.module.main()