diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index 67ff467105..ee7cc20fc1 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -937,7 +937,7 @@ files: labels: pagerduty maintainers: suprememoocow thaumos $modules/pagerduty_alert.py: - maintainers: ApsOps + maintainers: ApsOps xshen1 $modules/pagerduty_change.py: maintainers: adamvaughan $modules/pagerduty_user.py: diff --git a/changelogs/fragments/update-v2-pagerduty-alert.yml b/changelogs/fragments/update-v2-pagerduty-alert.yml new file mode 100644 index 0000000000..1f34b17fcb --- /dev/null +++ b/changelogs/fragments/update-v2-pagerduty-alert.yml @@ -0,0 +1,2 @@ +minor_changes: + - pagerduty - adds in option to use v2 API for creating pagerduty incidents (https://github.com/ansible-collections/community.general/issues/6151) diff --git a/plugins/modules/pagerduty_alert.py b/plugins/modules/pagerduty_alert.py index 66013b94a0..de451051f1 100644 --- a/plugins/modules/pagerduty_alert.py +++ b/plugins/modules/pagerduty_alert.py @@ -16,6 +16,7 @@ description: - This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events author: - "Amanpreet Singh (@ApsOps)" + - "Xiao Shen (@xshen1)" requirements: - PagerDuty API access extends_documentation_fragment: @@ -30,20 +31,25 @@ options: type: str description: - PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API. + api_key: + type: str + description: + - The pagerduty API key (readonly access), generated on the pagerduty site. + - Required if O(api_version=v1). + integration_key: + type: str + description: + - The GUID of one of your 'Generic API' services. + - This is the 'integration key' listed on a 'Integrations' tab of PagerDuty service. service_id: type: str description: - ID of PagerDuty service when incidents will be triggered, acknowledged or resolved. - required: true + - Required if O(api_version=v1). service_key: type: str description: - - The GUID of one of your "Generic API" services. Obsolete. Please use O(integration_key). - integration_key: - type: str - description: - - The GUID of one of your "Generic API" services. - - This is the "integration key" listed on a "Integrations" tab of PagerDuty service. + - The GUID of one of your 'Generic API' services. Obsolete. Please use O(integration_key). state: type: str description: @@ -53,30 +59,17 @@ options: - 'triggered' - 'acknowledged' - 'resolved' - api_key: + api_version: type: str description: - - The pagerduty API key (readonly access), generated on the pagerduty site. - required: true - desc: - type: str - description: - - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated version) - will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI. - The maximum length is 1024 characters. - - For O(state=acknowledged) or O(state=resolved) - Text that will appear in the incident's log associated with this event. - required: false - default: Created via Ansible - incident_key: - type: str - description: - - Identifies the incident to which this O(state) should be applied. - - For O(state=triggered) - If there's no open (i.e. unresolved) incident with this key, a new one will be created. If there's already an - open incident with a matching key, this event will be appended to that incident's log. The event key provides an easy way to "de-dup" - problem reports. - - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident was first opened by a - trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded. - required: false + - The API version we want to use to run the module. + - V1 is more limited with option we can provide to trigger incident. + - V2 has more variables for example, O(severity), O(source), O(custom_details), etc. + default: 'v1' + choices: + - 'v1' + - 'v2' + version_added: 7.4.0 client: type: str description: @@ -87,6 +80,75 @@ options: description: - The URL of the monitoring client that is triggering this event. required: false + component: + type: str + description: + - Component of the source machine that is responsible for the event, for example C(mysql) or C(eth0). + required: false + version_added: 7.4.0 + custom_details: + type: dict + description: + - Additional details about the event and affected system. + - A dictionary with custom keys and values. + required: false + version_added: 7.4.0 + desc: + type: str + description: + - For O(state=triggered) - Required. Short description of the problem that led to this trigger. This field (or a truncated version) + will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI. + The maximum length is 1024 characters. + - For O(state=acknowledged) or O(state=resolved) - Text that will appear in the incident's log associated with this event. + required: false + default: Created via Ansible + incident_class: + type: str + description: + - The class/type of the event, for example C(ping failure) or C(cpu load). + required: false + version_added: 7.4.0 + incident_key: + type: str + description: + - Identifies the incident to which this O(state) should be applied. + - For O(state=triggered) - If there's no open (i.e. unresolved) incident with this key, a new one will be created. If there's already an + open incident with a matching key, this event will be appended to that incident's log. The event key provides an easy way to 'de-dup' + problem reports. If no O(incident_key) is provided, then it will be generated by PagerDuty. + - For O(state=acknowledged) or O(state=resolved) - This should be the incident_key you received back when the incident was first opened by a + trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded. + required: false + link_url: + type: str + description: + - Relevant link url to the alert. For example, the website or the job link. + required: false + version_added: 7.4.0 + link_text: + type: str + description: + - A short decription of the link_url. + required: false + version_added: 7.4.0 + source: + type: str + description: + - The unique location of the affected system, preferably a hostname or FQDN. + - Required in case of O(state=trigger) and O(api_version=v2). + required: false + version_added: 7.4.0 + severity: + type: str + description: + - The perceived severity of the status the event is describing with respect to the affected system. + - Required in case of O(state=trigger) and O(api_version=v2). + default: 'critical' + choices: + - 'critical' + - 'warning' + - 'error' + - 'info' + version_added: 7.4.0 ''' EXAMPLES = ''' @@ -127,12 +189,50 @@ EXAMPLES = ''' state: resolved incident_key: somekey desc: "some text for incident's log" + +- name: Trigger an v2 incident with just the basic options + community.general.pagerduty_alert: + integration_key: xxx + api_version: v2 + source: My Ansible Script + state: triggered + desc: problem that led to this trigger + +- name: Trigger an v2 incident with more options + community.general.pagerduty_alert: + integration_key: xxx + api_version: v2 + source: My Ansible Script + state: triggered + desc: problem that led to this trigger + incident_key: somekey + client: Sample Monitoring Service + client_url: http://service.example.com + component: mysql + incident_class: ping failure + link_url: https://pagerduty.com + link_text: PagerDuty + +- name: Acknowledge an incident based on incident_key using v2 + community.general.pagerduty_alert: + api_version: v2 + integration_key: xxx + incident_key: somekey + state: acknowledged + +- name: Resolve an incident based on incident_key + community.general.pagerduty_alert: + api_version: v2 + integration_key: xxx + incident_key: somekey + state: resolved ''' import json from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.urls import fetch_url from ansible.module_utils.six.moves.urllib.parse import urlparse, urlencode, urlunparse +from datetime import datetime def check(module, name, state, service_id, integration_key, api_key, incident_key=None, http_call=fetch_url): @@ -175,8 +275,8 @@ def check(module, name, state, service_id, integration_key, api_key, incident_ke return incidents[0], False -def send_event(module, service_key, event_type, desc, - incident_key=None, client=None, client_url=None): +def send_event_v1(module, service_key, event_type, desc, + incident_key=None, client=None, client_url=None): url = "https://events.pagerduty.com/generic/2010-04-15/create_event.json" headers = { "Content-type": "application/json" @@ -200,61 +300,127 @@ def send_event(module, service_key, event_type, desc, return json_out +def send_event_v2(module, service_key, event_type, payload, link, + incident_key=None, client=None, client_url=None): + url = "https://events.pagerduty.com/v2/enqueue" + headers = { + "Content-type": "application/json" + } + data = { + "routing_key": service_key, + "event_action": event_type, + "payload": payload, + "client": client, + "client_url": client_url, + } + if link: + data["links"] = [link] + if incident_key: + data["dedup_key"] = incident_key + if event_type != "trigger": + data.pop("payload") + response, info = fetch_url(module, url, method="post", + headers=headers, data=json.dumps(data)) + if info["status"] != 202: + module.fail_json(msg="failed to %s. Reason: %s" % + (event_type, info['msg'])) + json_out = json.loads(response.read()) + return json_out, True + + def main(): module = AnsibleModule( argument_spec=dict( name=dict(required=False), - service_id=dict(required=True), - service_key=dict(required=False, no_log=True), + api_key=dict(required=False, no_log=True), integration_key=dict(required=False, no_log=True), - api_key=dict(required=True, no_log=True), - state=dict(required=True, - choices=['triggered', 'acknowledged', 'resolved']), - client=dict(required=False, default=None), - client_url=dict(required=False, default=None), + service_id=dict(required=False), + service_key=dict(required=False, no_log=True), + state=dict( + required=True, choices=['triggered', 'acknowledged', 'resolved'] + ), + api_version=dict(type='str', default='v1', choices=['v1', 'v2']), + client=dict(required=False), + client_url=dict(required=False), + component=dict(required=False), + custom_details=dict(required=False, type='dict'), desc=dict(required=False, default='Created via Ansible'), - incident_key=dict(required=False, default=None, no_log=False) + incident_class=dict(required=False), + incident_key=dict(required=False, no_log=False), + link_url=dict(required=False), + link_text=dict(required=False), + source=dict(required=False), + severity=dict( + default='critical', choices=['critical', 'warning', 'error', 'info'] + ), ), - supports_check_mode=True + required_if=[ + ('api_version', 'v1', ['service_id', 'api_key']), + ('state', 'acknowledged', ['incident_key']), + ('state', 'resolved', ['incident_key']), + ], + required_one_of=[('service_key', 'integration_key')], + supports_check_mode=True, ) name = module.params['name'] - service_id = module.params['service_id'] - integration_key = module.params['integration_key'] - service_key = module.params['service_key'] - api_key = module.params['api_key'] - state = module.params['state'] - client = module.params['client'] - client_url = module.params['client_url'] - desc = module.params['desc'] - incident_key = module.params['incident_key'] - + service_id = module.params.get('service_id') + integration_key = module.params.get('integration_key') + service_key = module.params.get('service_key') + api_key = module.params.get('api_key') + state = module.params.get('state') + client = module.params.get('client') + client_url = module.params.get('client_url') + desc = module.params.get('desc') + incident_key = module.params.get('incident_key') + payload = { + 'summary': desc, + 'source': module.params.get('source'), + 'timestamp': datetime.now().isoformat(), + 'severity': module.params.get('severity'), + 'component': module.params.get('component'), + 'class': module.params.get('incident_class'), + 'custom_details': module.params.get('custom_details'), + } + link = {} + if module.params.get('link_url'): + link['href'] = module.params.get('link_url') + if module.params.get('link_text'): + link['text'] = module.params.get('link_text') if integration_key is None: - if service_key is not None: - integration_key = service_key - module.warn('"service_key" is obsolete parameter and will be removed.' - ' Please, use "integration_key" instead') - else: - module.fail_json(msg="'integration_key' is required parameter") + integration_key = service_key + module.warn( + '"service_key" is obsolete parameter and will be removed.' + ' Please, use "integration_key" instead' + ) state_event_dict = { 'triggered': 'trigger', 'acknowledged': 'acknowledge', - 'resolved': 'resolve' + 'resolved': 'resolve', } event_type = state_event_dict[state] - - if event_type != 'trigger' and incident_key is None: - module.fail_json(msg="incident_key is required for " - "acknowledge or resolve events") - - out, changed = check(module, name, state, service_id, - integration_key, api_key, incident_key) - - if not module.check_mode and changed is True: - out = send_event(module, integration_key, event_type, desc, - incident_key, client, client_url) + if module.params.get('api_version') == 'v1': + out, changed = check(module, name, state, service_id, + integration_key, api_key, incident_key) + if not module.check_mode and changed is True: + out = send_event_v1(module, integration_key, event_type, desc, + incident_key, client, client_url) + else: + changed = True + if event_type == 'trigger' and not payload['source']: + module.fail_json(msg='"service" is a required variable for v2 api endpoint.') + out, changed = send_event_v2( + module, + integration_key, + event_type, + payload, + link, + incident_key, + client, + client_url, + ) module.exit_json(result=out, changed=changed) diff --git a/tests/unit/plugins/modules/test_pagerduty_alert.py b/tests/unit/plugins/modules/test_pagerduty_alert.py index 3df992b42d..958bd3fab7 100644 --- a/tests/unit/plugins/modules/test_pagerduty_alert.py +++ b/tests/unit/plugins/modules/test_pagerduty_alert.py @@ -7,6 +7,10 @@ __metaclass__ = type from ansible_collections.community.general.tests.unit.compat import unittest from ansible_collections.community.general.plugins.modules import pagerduty_alert +import json +import pytest +from ansible_collections.community.general.tests.unit.compat.mock import patch +from ansible_collections.community.general.tests.unit.plugins.modules.utils import AnsibleExitJson, AnsibleFailJson, ModuleTestCase, set_module_args class PagerDutyAlertsTest(unittest.TestCase): @@ -44,3 +48,106 @@ class PagerDutyAlertsTest(unittest.TestCase): class Response(object): def read(self): return '{"incidents":[{"id": "incident_id", "status": "triggered"}]}' + + +class TestPagerDutyAlertModule(ModuleTestCase): + def setUp(self): + super(TestPagerDutyAlertModule, self).setUp() + self.module = pagerduty_alert + + def tearDown(self): + super(TestPagerDutyAlertModule, self).tearDown() + + @pytest.fixture + def fetch_url_mock(self, mocker): + return mocker.patch('ansible.module_utils.monitoring.pagerduty_change.fetch_url') + + def test_module_fail_when_required_args_missing(self): + with self.assertRaises(AnsibleFailJson): + set_module_args({}) + self.module.main() + + def test_ensure_alert_created_with_minimal_data(self): + set_module_args({ + 'state': 'triggered', + 'api_version': 'v2', + 'integration_key': 'test', + 'source': 'My Ansible Script', + 'desc': 'Description for alert' + }) + + with patch.object(pagerduty_alert, 'fetch_url') as fetch_url_mock: + fetch_url_mock.return_value = (Response(), {"status": 202}) + with self.assertRaises(AnsibleExitJson): + self.module.main() + + assert fetch_url_mock.call_count == 1 + url = fetch_url_mock.call_args[0][1] + json_data = fetch_url_mock.call_args[1]['data'] + data = json.loads(json_data) + + assert url == 'https://events.pagerduty.com/v2/enqueue' + assert data['routing_key'] == 'test' + assert data['event_action'] == 'trigger' + assert data['payload']['summary'] == 'Description for alert' + assert data['payload']['source'] == 'My Ansible Script' + assert data['payload']['severity'] == 'critical' + assert data['payload']['timestamp'] is not None + + def test_ensure_alert_created_with_full_data(self): + set_module_args({ + 'api_version': 'v2', + 'component': 'mysql', + 'custom_details': {'environment': 'production', 'notes': 'this is a test note'}, + 'desc': 'Description for alert', + 'incident_class': 'ping failure', + 'integration_key': 'test', + 'link_url': 'https://pagerduty.com', + 'link_text': 'PagerDuty', + 'state': 'triggered', + 'source': 'My Ansible Script', + }) + + with patch.object(pagerduty_alert, 'fetch_url') as fetch_url_mock: + fetch_url_mock.return_value = (Response(), {"status": 202}) + with self.assertRaises(AnsibleExitJson): + self.module.main() + + assert fetch_url_mock.call_count == 1 + url = fetch_url_mock.call_args[0][1] + json_data = fetch_url_mock.call_args[1]['data'] + data = json.loads(json_data) + + assert url == 'https://events.pagerduty.com/v2/enqueue' + assert data['routing_key'] == 'test' + assert data['payload']['summary'] == 'Description for alert' + assert data['payload']['source'] == 'My Ansible Script' + assert data['payload']['class'] == 'ping failure' + assert data['payload']['component'] == 'mysql' + assert data['payload']['custom_details']['environment'] == 'production' + assert data['payload']['custom_details']['notes'] == 'this is a test note' + assert data['links'][0]['href'] == 'https://pagerduty.com' + assert data['links'][0]['text'] == 'PagerDuty' + + def test_ensure_alert_acknowledged(self): + set_module_args({ + 'state': 'acknowledged', + 'api_version': 'v2', + 'integration_key': 'test', + 'incident_key': 'incident_test_id', + }) + + with patch.object(pagerduty_alert, 'fetch_url') as fetch_url_mock: + fetch_url_mock.return_value = (Response(), {"status": 202}) + with self.assertRaises(AnsibleExitJson): + self.module.main() + + assert fetch_url_mock.call_count == 1 + url = fetch_url_mock.call_args[0][1] + json_data = fetch_url_mock.call_args[1]['data'] + data = json.loads(json_data) + + assert url == 'https://events.pagerduty.com/v2/enqueue' + assert data['routing_key'] == 'test' + assert data['event_action'] == 'acknowledge' + assert data['dedup_key'] == 'incident_test_id'