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

@@ -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:

plugins/modules/alerta_customer.py

@@ -0,0 +1 @@
+./monitoring/alerta_customer.py

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()

tests/integration/targets/alerta_customer/aliases

@@ -0,0 +1,2 @@
+shippable/posix/group1
+disabled

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

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

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()