ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

[PR #7183/6012d262 backport][stable-7] feat: pagerduty_alert: Adds in use of v2 api provided (#7229)

Browse source 
feat: pagerduty_alert: Adds in use of v2 api provided (#7183)

* feat: pagerduty_alert: Adds in use of v2 api provided

* doc: Adds xishen1 to maintainer

* Pagerduty_alert: documentation change

* pagerduty_alert: update documentation

* pagerduty_alert: update periods

* pagerduty_alert: update documentation

(cherry picked from commit 6012d2623e)

Co-authored-by: xshen1 <araticroyal1998@gmail.com>
This commit is contained in:
patchback[bot] 2023-09-10 09:00:28 +02:00 committed by GitHub
parent c94fa6132d
commit 56edbfc539
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 344 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/BOTMETA.yml vendored
View file

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

2
changelogs/fragments/update-v2-pagerduty-alert.yml Normal file
View file

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

302
plugins/modules/pagerduty_alert.py
View file

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

107
tests/unit/plugins/modules/test_pagerduty_alert.py
View file

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