mirror of https://github.com/ansible/ansible.git
Define module for managing E-Series email alerts (#42643)
Email alerts can be enabled for an E-Series system to provide information to interested users by email when a warning or critical level event occurs on the system. This module will allow a system owner to configure whether or not system alerts are enabled, and who will receive them.pull/44749/merge
Michael Price
6 years ago
committed by
John R Barker
parent
97157cf876
commit
054b87acb8
@ -0,0 +1,280 @@
|
||||
#!/usr/bin/python
|
||||
|
||||
# (c) 2018, NetApp, Inc
|
||||
# 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
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': ['preview'],
|
||||
'supported_by': 'community'}
|
||||
|
||||
DOCUMENTATION = """
|
||||
---
|
||||
module: netapp_e_alerts
|
||||
short_description: NetApp E-Series manage email notification settings
|
||||
description:
|
||||
- Certain E-Series systems have the capability to send email notifications on potentially critical events.
|
||||
- This module will allow the owner of the system to specify email recipients for these messages.
|
||||
version_added: '2.7'
|
||||
author: Michael Price (@lmprice)
|
||||
extends_documentation_fragment:
|
||||
- netapp.eseries
|
||||
options:
|
||||
state:
|
||||
description:
|
||||
- Enable/disable the sending of email-based alerts.
|
||||
default: enabled
|
||||
required: false
|
||||
choices:
|
||||
- enabled
|
||||
- disabled
|
||||
server:
|
||||
description:
|
||||
- A fully qualified domain name, IPv4 address, or IPv6 address of a mail server.
|
||||
- To use a fully qualified domain name, you must configure a DNS server on both controllers using
|
||||
M(netapp_e_mgmt_interface).
|
||||
- Required when I(state=enabled).
|
||||
required: no
|
||||
sender:
|
||||
description:
|
||||
- This is the sender that the recipient will see. It doesn't necessarily need to be a valid email account.
|
||||
- Required when I(state=enabled).
|
||||
required: no
|
||||
contact:
|
||||
description:
|
||||
- Allows the owner to specify some free-form contact information to be included in the emails.
|
||||
- This is typically utilized to provide a contact phone number.
|
||||
required: no
|
||||
recipients:
|
||||
description:
|
||||
- The email addresses that will receive the email notifications.
|
||||
- Required when I(state=enabled).
|
||||
required: no
|
||||
test:
|
||||
description:
|
||||
- When a change is detected in the configuration, a test email will be sent.
|
||||
- This may take a few minutes to process.
|
||||
- Only applicable if I(state=enabled).
|
||||
default: no
|
||||
type: bool
|
||||
log_path:
|
||||
description:
|
||||
- Path to a file on the Ansible control node to be used for debug logging
|
||||
required: no
|
||||
notes:
|
||||
- Check mode is supported.
|
||||
- Alertable messages are a subset of messages shown by the Major Event Log (MEL), of the storage-system. Examples
|
||||
of alertable messages include drive failures, failed controllers, loss of redundancy, and other warning/critical
|
||||
events.
|
||||
- This API is currently only supported with the Embedded Web Services API v2.0 and higher.
|
||||
"""
|
||||
|
||||
EXAMPLES = """
|
||||
- name: Enable email-based alerting
|
||||
netapp_e_alerts:
|
||||
state: enabled
|
||||
sender: noreply@example.com
|
||||
server: mail@example.com
|
||||
contact: "Phone: 1-555-555-5555"
|
||||
recipients:
|
||||
- name1@example.com
|
||||
- name2@example.com
|
||||
api_url: "10.1.1.1:8443"
|
||||
api_username: "admin"
|
||||
api_password: "myPass"
|
||||
|
||||
- name: Disable alerting
|
||||
netapp_e_alerts:
|
||||
state: disabled
|
||||
api_url: "10.1.1.1:8443"
|
||||
api_username: "admin"
|
||||
api_password: "myPass"
|
||||
"""
|
||||
|
||||
RETURN = """
|
||||
msg:
|
||||
description: Success message
|
||||
returned: on success
|
||||
type: string
|
||||
sample: The settings have been updated.
|
||||
"""
|
||||
|
||||
import json
|
||||
import logging
|
||||
from pprint import pformat
|
||||
import re
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
from ansible.module_utils.netapp import request, eseries_host_argument_spec
|
||||
from ansible.module_utils._text import to_native
|
||||
|
||||
HEADERS = {
|
||||
"Content-Type": "application/json",
|
||||
"Accept": "application/json",
|
||||
}
|
||||
|
||||
|
||||
class Alerts(object):
|
||||
def __init__(self):
|
||||
argument_spec = eseries_host_argument_spec()
|
||||
argument_spec.update(dict(
|
||||
state=dict(type='str', required=False, default='enabled',
|
||||
choices=['enabled', 'disabled']),
|
||||
server=dict(type='str', required=False, ),
|
||||
sender=dict(type='str', required=False, ),
|
||||
contact=dict(type='str', required=False, ),
|
||||
recipients=dict(type='list', required=False, ),
|
||||
test=dict(type='bool', required=False, default=False, ),
|
||||
log_path=dict(type='str', required=False),
|
||||
))
|
||||
|
||||
required_if = [
|
||||
['state', 'enabled', ['server', 'sender', 'recipients']]
|
||||
]
|
||||
|
||||
self.module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True, required_if=required_if)
|
||||
args = self.module.params
|
||||
self.alerts = args['state'] == 'enabled'
|
||||
self.server = args['server']
|
||||
self.sender = args['sender']
|
||||
self.contact = args['contact']
|
||||
self.recipients = args['recipients']
|
||||
self.test = args['test']
|
||||
|
||||
self.ssid = args['ssid']
|
||||
self.url = args['api_url']
|
||||
self.creds = dict(url_password=args['api_password'],
|
||||
validate_certs=args['validate_certs'],
|
||||
url_username=args['api_username'], )
|
||||
|
||||
self.check_mode = self.module.check_mode
|
||||
|
||||
log_path = args['log_path']
|
||||
|
||||
# logging setup
|
||||
self._logger = logging.getLogger(self.__class__.__name__)
|
||||
|
||||
if log_path:
|
||||
logging.basicConfig(
|
||||
level=logging.DEBUG, filename=log_path, filemode='w',
|
||||
format='%(relativeCreated)dms %(levelname)s %(module)s.%(funcName)s:%(lineno)d\n %(message)s')
|
||||
|
||||
if not self.url.endswith('/'):
|
||||
self.url += '/'
|
||||
|
||||
# Very basic validation on email addresses: xx@yy.zz
|
||||
email = re.compile(r"[^@]+@[^@]+\.[^@]+")
|
||||
|
||||
if self.sender and not email.match(self.sender):
|
||||
self.module.fail_json(msg="The sender (%s) provided is not a valid email address." % self.sender)
|
||||
|
||||
if self.recipients is not None:
|
||||
for recipient in self.recipients:
|
||||
if not email.match(recipient):
|
||||
self.module.fail_json(msg="The recipient (%s) provided is not a valid email address." % recipient)
|
||||
|
||||
if len(self.recipients) < 1:
|
||||
self.module.fail_json(msg="At least one recipient address must be specified.")
|
||||
|
||||
def get_configuration(self):
|
||||
try:
|
||||
(rc, result) = request(self.url + 'storage-systems/%s/device-alerts' % self.ssid, headers=HEADERS,
|
||||
**self.creds)
|
||||
self._logger.info("Current config: %s", pformat(result))
|
||||
return result
|
||||
|
||||
except Exception as err:
|
||||
self.module.fail_json(msg="Failed to retrieve the alerts configuration! Array Id [%s]. Error [%s]."
|
||||
% (self.ssid, to_native(err)))
|
||||
|
||||
def update_configuration(self):
|
||||
config = self.get_configuration()
|
||||
update = False
|
||||
body = dict()
|
||||
|
||||
if self.alerts:
|
||||
body = dict(alertingEnabled=True)
|
||||
if not config['alertingEnabled']:
|
||||
update = True
|
||||
|
||||
body.update(emailServerAddress=self.server)
|
||||
if config['emailServerAddress'] != self.server:
|
||||
update = True
|
||||
|
||||
body.update(additionalContactInformation=self.contact, sendAdditionalContactInformation=True)
|
||||
if self.contact and (self.contact != config['additionalContactInformation']
|
||||
or not config['sendAdditionalContactInformation']):
|
||||
update = True
|
||||
|
||||
body.update(emailSenderAddress=self.sender)
|
||||
if config['emailSenderAddress'] != self.sender:
|
||||
update = True
|
||||
|
||||
self.recipients.sort()
|
||||
if config['recipientEmailAddresses']:
|
||||
config['recipientEmailAddresses'].sort()
|
||||
|
||||
body.update(recipientEmailAddresses=self.recipients)
|
||||
if config['recipientEmailAddresses'] != self.recipients:
|
||||
update = True
|
||||
|
||||
elif config['alertingEnabled']:
|
||||
body = dict(alertingEnabled=False)
|
||||
update = True
|
||||
|
||||
self._logger.debug(pformat(body))
|
||||
|
||||
if update and not self.check_mode:
|
||||
try:
|
||||
(rc, result) = request(self.url + 'storage-systems/%s/device-alerts' % self.ssid, method='POST',
|
||||
data=json.dumps(body), headers=HEADERS, **self.creds)
|
||||
# This is going to catch cases like a connection failure
|
||||
except Exception as err:
|
||||
self.module.fail_json(msg="We failed to set the storage-system name! Array Id [%s]. Error [%s]."
|
||||
% (self.ssid, to_native(err)))
|
||||
return update
|
||||
|
||||
def send_test_email(self):
|
||||
"""Send a test email to verify that the provided configuration is valid and functional."""
|
||||
if not self.check_mode:
|
||||
try:
|
||||
(rc, result) = request(self.url + 'storage-systems/%s/device-alerts/alert-email-test' % self.ssid,
|
||||
timeout=300, method='POST', headers=HEADERS, **self.creds)
|
||||
|
||||
if result['response'] != 'emailSentOK':
|
||||
self.module.fail_json(msg="The test email failed with status=[%s]! Array Id [%s]."
|
||||
% (result['response'], self.ssid))
|
||||
|
||||
# This is going to catch cases like a connection failure
|
||||
except Exception as err:
|
||||
self.module.fail_json(msg="We failed to send the test email! Array Id [%s]. Error [%s]."
|
||||
% (self.ssid, to_native(err)))
|
||||
|
||||
def update(self):
|
||||
update = self.update_configuration()
|
||||
|
||||
if self.test and update:
|
||||
self._logger.info("An update was detected and test=True, running a test.")
|
||||
self.send_test_email()
|
||||
|
||||
if self.alerts:
|
||||
msg = 'Alerting has been enabled using server=%s, sender=%s.' % (self.server, self.sender)
|
||||
else:
|
||||
msg = 'Alerting has been disabled.'
|
||||
|
||||
self.module.exit_json(msg=msg, changed=update, )
|
||||
|
||||
def __call__(self, *args, **kwargs):
|
||||
self.update()
|
||||
|
||||
|
||||
def main():
|
||||
alerts = Alerts()
|
||||
alerts()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
@ -0,0 +1,10 @@
|
||||
# This test is not enabled by default, but can be utilized by defining required variables in integration_config.yml
|
||||
# Example integration_config.yml:
|
||||
# ---
|
||||
#netapp_e_api_host: 10.113.1.111:8443
|
||||
#netapp_e_api_username: admin
|
||||
#netapp_e_api_password: myPass
|
||||
#netapp_e_ssid: 1
|
||||
|
||||
unsupported
|
||||
netapp/eseries
|
||||
@ -0,0 +1 @@
|
||||
- include_tasks: run.yml
|
||||
@ -0,0 +1,39 @@
|
||||
# Test code for the netapp_e_iscsi_interface module
|
||||
# (c) 2018, NetApp, Inc
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
|
||||
- name: NetApp Test ASUP module
|
||||
fail:
|
||||
msg: 'Please define netapp_e_api_username, netapp_e_api_password, netapp_e_api_host, and netapp_e_ssid.'
|
||||
when: netapp_e_api_username is undefined or netapp_e_api_password is undefined
|
||||
or netapp_e_api_host is undefined or netapp_e_ssid is undefined
|
||||
vars:
|
||||
defaults: &defaults
|
||||
api_url: "https://{{ netapp_e_api_host }}/devmgr/v2"
|
||||
api_username: "{{ netapp_e_api_username }}"
|
||||
api_password: "{{ netapp_e_api_password }}"
|
||||
ssid: "{{ netapp_e_ssid }}"
|
||||
validate_certs: no
|
||||
state: enabled
|
||||
server: mail.example.com
|
||||
sender: noreply@example.com
|
||||
recipients:
|
||||
- noreply@example.com
|
||||
|
||||
- name: set default vars
|
||||
set_fact:
|
||||
vars: *defaults
|
||||
|
||||
- name: Set the initial alerting settings
|
||||
netapp_e_alerts:
|
||||
<<: *defaults
|
||||
register: result
|
||||
|
||||
- name: Validate the idempotency of the module
|
||||
netapp_e_alerts:
|
||||
<<: *defaults
|
||||
register: result
|
||||
|
||||
- name: Ensure we still have the same settings, but had no change
|
||||
assert:
|
||||
that: not result.changed
|
||||
@ -0,0 +1,184 @@
|
||||
# (c) 2018, NetApp Inc.
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
import json
|
||||
|
||||
from ansible.modules.storage.netapp.netapp_e_alerts import Alerts
|
||||
from units.modules.utils import AnsibleExitJson, AnsibleFailJson, ModuleTestCase, set_module_args
|
||||
|
||||
__metaclass__ = type
|
||||
from ansible.compat.tests import mock
|
||||
|
||||
|
||||
class AlertsTest(ModuleTestCase):
|
||||
REQUIRED_PARAMS = {
|
||||
'api_username': 'rw',
|
||||
'api_password': 'password',
|
||||
'api_url': 'http://localhost',
|
||||
'ssid': '1',
|
||||
'state': 'disabled'
|
||||
}
|
||||
REQ_FUNC = 'ansible.modules.storage.netapp.netapp_e_alerts.request'
|
||||
|
||||
def _set_args(self, **kwargs):
|
||||
module_args = self.REQUIRED_PARAMS.copy()
|
||||
if kwargs is not None:
|
||||
module_args.update(kwargs)
|
||||
set_module_args(module_args)
|
||||
|
||||
def _validate_args(self, **kwargs):
|
||||
self._set_args(**kwargs)
|
||||
Alerts()
|
||||
|
||||
def test_validation_disable(self):
|
||||
"""Ensure a default configuration succeeds"""
|
||||
self._validate_args()
|
||||
|
||||
def test_validation_enable(self):
|
||||
"""Ensure a typical, default configuration succeeds"""
|
||||
self._validate_args(state='enabled', server='localhost', sender='x@y.z', recipients=['a@b.c'])
|
||||
|
||||
def test_validation_fail_required(self):
|
||||
"""Ensure we fail on missing configuration"""
|
||||
|
||||
# Missing recipients
|
||||
with self.assertRaises(AnsibleFailJson):
|
||||
self._validate_args(state='enabled', server='localhost', sender='x@y.z')
|
||||
Alerts()
|
||||
|
||||
# Missing sender
|
||||
with self.assertRaises(AnsibleFailJson):
|
||||
self._validate_args(state='enabled', server='localhost', recipients=['a@b.c'])
|
||||
Alerts()
|
||||
|
||||
# Missing server
|
||||
with self.assertRaises(AnsibleFailJson):
|
||||
self._validate_args(state='enabled', sender='x@y.z', recipients=['a@b.c'])
|
||||
|
||||
def test_validation_fail(self):
|
||||
# Empty recipients
|
||||
with self.assertRaises(AnsibleFailJson):
|
||||
self._validate_args(state='enabled', server='localhost', sender='x@y.z', recipients=[])
|
||||
|
||||
# Bad sender
|
||||
with self.assertRaises(AnsibleFailJson):
|
||||
self._validate_args(state='enabled', server='localhost', sender='y.z', recipients=['a@b.c'])
|
||||
|
||||
def test_get_configuration(self):
|
||||
"""Validate retrieving the current configuration"""
|
||||
self._set_args(state='enabled', server='localhost', sender='x@y.z', recipients=['a@b.c'])
|
||||
|
||||
expected = 'result'
|
||||
alerts = Alerts()
|
||||
# Expecting an update
|
||||
with mock.patch(self.REQ_FUNC, return_value=(200, expected)) as req:
|
||||
actual = alerts.get_configuration()
|
||||
self.assertEquals(expected, actual)
|
||||
self.assertEquals(req.call_count, 1)
|
||||
|
||||
def test_update_configuration(self):
|
||||
"""Validate updating the configuration"""
|
||||
initial = dict(alertingEnabled=True,
|
||||
emailServerAddress='localhost',
|
||||
sendAdditionalContactInformation=True,
|
||||
additionalContactInformation='None',
|
||||
emailSenderAddress='x@y.z',
|
||||
recipientEmailAddresses=['x@y.z']
|
||||
)
|
||||
|
||||
args = dict(state='enabled', server=initial['emailServerAddress'], sender=initial['emailSenderAddress'],
|
||||
contact=initial['additionalContactInformation'], recipients=initial['recipientEmailAddresses'])
|
||||
|
||||
self._set_args(**args)
|
||||
|
||||
alerts = Alerts()
|
||||
|
||||
# Ensure when trigger updates when each relevant field is changed
|
||||
with mock.patch(self.REQ_FUNC, return_value=(200, None)) as req:
|
||||
with mock.patch.object(alerts, 'get_configuration', return_value=initial):
|
||||
update = alerts.update_configuration()
|
||||
self.assertFalse(update)
|
||||
|
||||
alerts.sender = 'a@b.c'
|
||||
update = alerts.update_configuration()
|
||||
self.assertTrue(update)
|
||||
self._set_args(**args)
|
||||
|
||||
alerts.recipients = ['a@b.c']
|
||||
update = alerts.update_configuration()
|
||||
self.assertTrue(update)
|
||||
self._set_args(**args)
|
||||
|
||||
alerts.contact = 'abc'
|
||||
update = alerts.update_configuration()
|
||||
self.assertTrue(update)
|
||||
self._set_args(**args)
|
||||
|
||||
alerts.server = 'abc'
|
||||
update = alerts.update_configuration()
|
||||
self.assertTrue(update)
|
||||
|
||||
def test_send_test_email_check(self):
|
||||
"""Ensure we handle check_mode correctly"""
|
||||
self._set_args(test=True)
|
||||
alerts = Alerts()
|
||||
alerts.check_mode = True
|
||||
with mock.patch(self.REQ_FUNC) as req:
|
||||
with mock.patch.object(alerts, 'update_configuration', return_value=True):
|
||||
alerts.send_test_email()
|
||||
self.assertFalse(req.called)
|
||||
|
||||
def test_send_test_email(self):
|
||||
"""Ensure we send a test email if test=True"""
|
||||
self._set_args(test=True)
|
||||
alerts = Alerts()
|
||||
|
||||
with mock.patch(self.REQ_FUNC, return_value=(200, dict(response='emailSentOK'))) as req:
|
||||
alerts.send_test_email()
|
||||
self.assertTrue(req.called)
|
||||
|
||||
def test_send_test_email_fail(self):
|
||||
"""Ensure we fail if the test returned a failure status"""
|
||||
self._set_args(test=True)
|
||||
alerts = Alerts()
|
||||
|
||||
ret_msg = 'fail'
|
||||
with self.assertRaisesRegexp(AnsibleFailJson, ret_msg):
|
||||
with mock.patch(self.REQ_FUNC, return_value=(200, dict(response=ret_msg))) as req:
|
||||
alerts.send_test_email()
|
||||
self.assertTrue(req.called)
|
||||
|
||||
def test_send_test_email_fail_connection(self):
|
||||
"""Ensure we fail cleanly if we hit a connection failure"""
|
||||
self._set_args(test=True)
|
||||
alerts = Alerts()
|
||||
|
||||
with self.assertRaisesRegexp(AnsibleFailJson, r"failed to send"):
|
||||
with mock.patch(self.REQ_FUNC, side_effect=Exception) as req:
|
||||
alerts.send_test_email()
|
||||
self.assertTrue(req.called)
|
||||
|
||||
def test_update(self):
|
||||
# Ensure that when test is enabled and alerting is enabled, we run the test
|
||||
self._set_args(state='enabled', server='localhost', sender='x@y.z', recipients=['a@b.c'], test=True)
|
||||
alerts = Alerts()
|
||||
with self.assertRaisesRegexp(AnsibleExitJson, r"enabled"):
|
||||
with mock.patch.object(alerts, 'update_configuration', return_value=True):
|
||||
with mock.patch.object(alerts, 'send_test_email') as test:
|
||||
alerts.update()
|
||||
self.assertTrue(test.called)
|
||||
|
||||
# Ensure we don't run a test when changed=False
|
||||
with self.assertRaisesRegexp(AnsibleExitJson, r"enabled"):
|
||||
with mock.patch.object(alerts, 'update_configuration', return_value=False):
|
||||
with mock.patch.object(alerts, 'send_test_email') as test:
|
||||
alerts.update()
|
||||
self.assertFalse(test.called)
|
||||
|
||||
# Ensure that test is not called when we have alerting disabled
|
||||
self._set_args(state='disabled')
|
||||
alerts = Alerts()
|
||||
with self.assertRaisesRegexp(AnsibleExitJson, r"disabled"):
|
||||
with mock.patch.object(alerts, 'update_configuration', return_value=True):
|
||||
with mock.patch.object(alerts, 'send_test_email') as test:
|
||||
alerts.update()
|
||||
self.assertFalse(test.called)
|
||||
Loading…
Reference in New Issue