Merge pull request #260 from smashwilson/rax_mon

Rackspace Cloud Monitoring modules

cloud/rackspace/rax_mon_alarm.py

@@ -0,0 +1,227 @@
+#!/usr/bin/python
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
+DOCUMENTATION = '''
+---
+module: rax_mon_alarm
+short_description: Create or delete a Rackspace Cloud Monitoring alarm.
+description:
+- Create or delete a Rackspace Cloud Monitoring alarm that associates an
+  existing rax_mon_entity, rax_mon_check, and rax_mon_notification_plan with
+  criteria that specify what conditions will trigger which levels of
+  notifications. Rackspace monitoring module flow | rax_mon_entity ->
+  rax_mon_check -> rax_mon_notification -> rax_mon_notification_plan ->
+  *rax_mon_alarm*
+version_added: "1.9"
+options:
+  state:
+    description:
+    - Ensure that the alarm with this C(label) exists or does not exist.
+    choices: [ "present", "absent" ]
+    required: false
+    default: present
+  label:
+    description:
+    - Friendly name for this alarm, used to achieve idempotence. Must be a String
+      between 1 and 255 characters long.
+    required: true
+  entity_id:
+    description:
+    - ID of the entity this alarm is attached to. May be acquired by registering
+      the value of a rax_mon_entity task.
+    required: true
+  check_id:
+    description:
+    - ID of the check that should be alerted on. May be acquired by registering
+      the value of a rax_mon_check task.
+    required: true
+  notification_plan_id:
+    description:
+    - ID of the notification plan to trigger if this alarm fires. May be acquired
+      by registering the value of a rax_mon_notification_plan task.
+    required: true
+  criteria:
+    description:
+    - Alarm DSL that describes alerting conditions and their output states. Must
+      be between 1 and 16384 characters long. See
+      http://docs.rackspace.com/cm/api/v1.0/cm-devguide/content/alerts-language.html
+      for a reference on the alerting language.
+  disabled:
+    description:
+    - If yes, create this alarm, but leave it in an inactive state. Defaults to
+      no.
+    choices: [ "yes", "no" ]
+  metadata:
+    description:
+    - Arbitrary key/value pairs to accompany the alarm. Must be a hash of String
+      keys and values between 1 and 255 characters long.
+author: Ash Wilson
+extends_documentation_fragment: rackspace.openstack
+'''
+
+EXAMPLES = '''
+- name: Alarm example
+  gather_facts: False
+  hosts: local
+  connection: local
+  tasks:
+  - name: Ensure that a specific alarm exists.
+    rax_mon_alarm:
+      credentials: ~/.rax_pub
+      state: present
+      label: uhoh
+      entity_id: "{{ the_entity['entity']['id'] }}"
+      check_id: "{{ the_check['check']['id'] }}"
+      notification_plan_id: "{{ defcon1['notification_plan']['id'] }}"
+      criteria: >
+        if (rate(metric['average']) > 10) {
+          return new AlarmStatus(WARNING);
+        }
+        return new AlarmStatus(OK);
+    register: the_alarm
+'''
+
+try:
+    import pyrax
+    HAS_PYRAX = True
+except ImportError:
+    HAS_PYRAX = False
+
+def alarm(module, state, label, entity_id, check_id, notification_plan_id, criteria,
+          disabled, metadata):
+
+    if len(label) < 1 or len(label) > 255:
+        module.fail_json(msg='label must be between 1 and 255 characters long')
+
+    if criteria and len(criteria) < 1 or len(criteria) > 16384:
+        module.fail_json(msg='criteria must be between 1 and 16384 characters long')
+
+    # Coerce attributes.
+
+    changed = False
+    alarm = None
+
+    cm = pyrax.cloud_monitoring
+    if not cm:
+        module.fail_json(msg='Failed to instantiate client. This typically '
+                             'indicates an invalid region or an incorrectly '
+                             'capitalized region name.')
+
+    existing = [a for a in cm.list_alarms(entity_id) if a.label == label]
+
+    if existing:
+        alarm = existing[0]
+
+    if state == 'present':
+        should_create = False
+        should_update = False
+        should_delete = False
+
+        if len(existing) > 1:
+            module.fail_json(msg='%s existing alarms have the label %s.' %
+                                 (len(existing), label))
+
+        if alarm:
+            if check_id != alarm.check_id or notification_plan_id != alarm.notification_plan_id:
+                should_delete = should_create = True
+
+            should_update = (disabled and disabled != alarm.disabled) or \
+                (metadata and metadata != alarm.metadata) or \
+                (criteria and criteria != alarm.criteria)
+
+            if should_update and not should_delete:
+                cm.update_alarm(entity=entity_id, alarm=alarm,
+                                criteria=criteria, disabled=disabled,
+                                label=label, metadata=metadata)
+                changed = True
+
+            if should_delete:
+                alarm.delete()
+                changed = True
+        else:
+            should_create = True
+
+        if should_create:
+            alarm = cm.create_alarm(entity=entity_id, check=check_id,
+                                    notification_plan=notification_plan_id,
+                                    criteria=criteria, disabled=disabled, label=label,
+                                    metadata=metadata)
+            changed = True
+    else:
+        for a in existing:
+            a.delete()
+            changed = True
+
+    if alarm:
+        alarm_dict = {
+            "id": alarm.id,
+            "label": alarm.label,
+            "check_id": alarm.check_id,
+            "notification_plan_id": alarm.notification_plan_id,
+            "criteria": alarm.criteria,
+            "disabled": alarm.disabled,
+            "metadata": alarm.metadata
+        }
+        module.exit_json(changed=changed, alarm=alarm_dict)
+    else:
+        module.exit_json(changed=changed)
+
+def main():
+    argument_spec = rax_argument_spec()
+    argument_spec.update(
+        dict(
+            state=dict(default='present', choices=['present', 'absent']),
+            label=dict(required=True),
+            entity_id=dict(required=True),
+            check_id=dict(required=True),
+            notification_plan_id=dict(required=True),
+            criteria=dict(),
+            disabled=dict(type='bool', default=False),
+            metadata=dict(type='dict')
+        )
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        required_together=rax_required_together()
+    )
+
+    if not HAS_PYRAX:
+        module.fail_json(msg='pyrax is required for this module')
+
+    state = module.params.get('state')
+    label = module.params.get('label')
+    entity_id = module.params.get('entity_id')
+    check_id = module.params.get('check_id')
+    notification_plan_id = module.params.get('notification_plan_id')
+    criteria = module.params.get('criteria')
+    disabled = module.boolean(module.params.get('disabled'))
+    metadata = module.params.get('metadata')
+
+    setup_rax_module(module, pyrax)
+
+    alarm(module, state, label, entity_id, check_id, notification_plan_id,
+          criteria, disabled, metadata)
+
+
+# Import module snippets
+from ansible.module_utils.basic import *
+from ansible.module_utils.rax import *
+
+# Invoke the module.
+main()

cloud/rackspace/rax_mon_check.py

@@ -0,0 +1,313 @@
+#!/usr/bin/python
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
+DOCUMENTATION = '''
+---
+module: rax_mon_check
+short_description: Create or delete a Rackspace Cloud Monitoring check for an
+                   existing entity.
+description:
+- Create or delete a Rackspace Cloud Monitoring check associated with an
+  existing rax_mon_entity. A check is a specific test or measurement that is
+  performed, possibly from different monitoring zones, on the systems you
+  monitor. Rackspace monitoring module flow | rax_mon_entity ->
+  *rax_mon_check* -> rax_mon_notification -> rax_mon_notification_plan ->
+  rax_mon_alarm
+version_added: "1.9"
+options:
+  state:
+    description:
+    - Ensure that a check with this C(label) exists or does not exist.
+    choices: ["present", "absent"]
+  entity_id:
+    description:
+    - ID of the rax_mon_entity to target with this check.
+    required: true
+  label:
+    description:
+    - Defines a label for this check, between 1 and 64 characters long.
+    required: true
+  check_type:
+    description:
+    - The type of check to create. C(remote.) checks may be created on any
+      rax_mon_entity. C(agent.) checks may only be created on rax_mon_entities
+      that have a non-null C(agent_id).
+    choices:
+    - remote.dns
+    - remote.ftp-banner
+    - remote.http
+    - remote.imap-banner
+    - remote.mssql-banner
+    - remote.mysql-banner
+    - remote.ping
+    - remote.pop3-banner
+    - remote.postgresql-banner
+    - remote.smtp-banner
+    - remote.smtp
+    - remote.ssh
+    - remote.tcp
+    - remote.telnet-banner
+    - agent.filesystem
+    - agent.memory
+    - agent.load_average
+    - agent.cpu
+    - agent.disk
+    - agent.network
+    - agent.plugin
+    required: true
+  monitoring_zones_poll:
+    description:
+    - Comma-separated list of the names of the monitoring zones the check should
+      run from. Available monitoring zones include mzdfw, mzhkg, mziad, mzlon,
+      mzord and mzsyd. Required for remote.* checks; prohibited for agent.* checks.
+  target_hostname:
+    description:
+    - One of `target_hostname` and `target_alias` is required for remote.* checks,
+      but prohibited for agent.* checks. The hostname this check should target.
+      Must be a valid IPv4, IPv6, or FQDN.
+  target_alias:
+    description:
+    - One of `target_alias` and `target_hostname` is required for remote.* checks,
+      but prohibited for agent.* checks. Use the corresponding key in the entity's
+      `ip_addresses` hash to resolve an IP address to target.
+  details:
+    description:
+    - Additional details specific to the check type. Must be a hash of strings
+      between 1 and 255 characters long, or an array or object containing 0 to
+      256 items.
+  disabled:
+    description:
+    - If "yes", ensure the check is created, but don't actually use it yet.
+    choices: [ "yes", "no" ]
+  metadata:
+    description:
+    - Hash of arbitrary key-value pairs to accompany this check if it fires.
+      Keys and values must be strings between 1 and 255 characters long.
+  period:
+    description:
+    - The number of seconds between each time the check is performed. Must be
+      greater than the minimum period set on your account.
+  timeout:
+    description:
+    - The number of seconds this check will wait when attempting to collect
+      results. Must be less than the period.
+author: Ash Wilson
+extends_documentation_fragment: rackspace.openstack
+'''
+
+EXAMPLES = '''
+- name: Create a monitoring check
+  gather_facts: False
+  hosts: local
+  connection: local
+  tasks:
+  - name: Associate a check with an existing entity.
+    rax_mon_check:
+      credentials: ~/.rax_pub
+      state: present
+      entity_id: "{{ the_entity['entity']['id'] }}"
+      label: the_check
+      check_type: remote.ping
+      monitoring_zones_poll: mziad,mzord,mzdfw
+      details:
+        count: 10
+      meta:
+        hurf: durf
+    register: the_check
+'''
+
+try:
+    import pyrax
+    HAS_PYRAX = True
+except ImportError:
+    HAS_PYRAX = False
+
+def cloud_check(module, state, entity_id, label, check_type,
+                monitoring_zones_poll, target_hostname, target_alias, details,
+                disabled, metadata, period, timeout):
+
+    # Coerce attributes.
+
+    if monitoring_zones_poll and not isinstance(monitoring_zones_poll, list):
+        monitoring_zones_poll = [monitoring_zones_poll]
+
+    if period:
+        period = int(period)
+
+    if timeout:
+        timeout = int(timeout)
+
+    changed = False
+    check = None
+
+    cm = pyrax.cloud_monitoring
+    if not cm:
+        module.fail_json(msg='Failed to instantiate client. This typically '
+                             'indicates an invalid region or an incorrectly '
+                             'capitalized region name.')
+
+    entity = cm.get_entity(entity_id)
+    if not entity:
+        module.fail_json(msg='Failed to instantiate entity. "%s" may not be'
+                             ' a valid entity id.' % entity_id)
+
+    existing = [e for e in entity.list_checks() if e.label == label]
+
+    if existing:
+        check = existing[0]
+
+    if state == 'present':
+        if len(existing) > 1:
+            module.fail_json(msg='%s existing checks have a label of %s.' %
+                                 (len(existing), label))
+
+        should_delete = False
+        should_create = False
+        should_update = False
+
+        if check:
+            # Details may include keys set to default values that are not
+            # included in the initial creation.
+            #
+            # Only force a recreation of the check if one of the *specified*
+            # keys is missing or has a different value.
+            if details:
+                for (key, value) in details.iteritems():
+                    if key not in check.details:
+                        should_delete = should_create = True
+                    elif value != check.details[key]:
+                        should_delete = should_create = True
+
+            should_update = label != check.label or \
+                (target_hostname and target_hostname != check.target_hostname) or \
+                (target_alias and target_alias != check.target_alias) or \
+                (disabled != check.disabled) or \
+                (metadata and metadata != check.metadata) or \
+                (period and period != check.period) or \
+                (timeout and timeout != check.timeout) or \
+                (monitoring_zones_poll and monitoring_zones_poll != check.monitoring_zones_poll)
+
+            if should_update and not should_delete:
+                check.update(label=label,
+                             disabled=disabled,
+                             metadata=metadata,
+                             monitoring_zones_poll=monitoring_zones_poll,
+                             timeout=timeout,
+                             period=period,
+                             target_alias=target_alias,
+                             target_hostname=target_hostname)
+                changed = True
+        else:
+            # The check doesn't exist yet.
+            should_create = True
+
+        if should_delete:
+            check.delete()
+
+        if should_create:
+            check = cm.create_check(entity,
+                                    label=label,
+                                    check_type=check_type,
+                                    target_hostname=target_hostname,
+                                    target_alias=target_alias,
+                                    monitoring_zones_poll=monitoring_zones_poll,
+                                    details=details,
+                                    disabled=disabled,
+                                    metadata=metadata,
+                                    period=period,
+                                    timeout=timeout)
+            changed = True
+    elif state == 'absent':
+        if check:
+            check.delete()
+            changed = True
+    else:
+        module.fail_json(msg='state must be either present or absent.')
+
+    if check:
+        check_dict = {
+            "id": check.id,
+            "label": check.label,
+            "type": check.type,
+            "target_hostname": check.target_hostname,
+            "target_alias": check.target_alias,
+            "monitoring_zones_poll": check.monitoring_zones_poll,
+            "details": check.details,
+            "disabled": check.disabled,
+            "metadata": check.metadata,
+            "period": check.period,
+            "timeout": check.timeout
+        }
+        module.exit_json(changed=changed, check=check_dict)
+    else:
+        module.exit_json(changed=changed)
+
+def main():
+    argument_spec = rax_argument_spec()
+    argument_spec.update(
+        dict(
+            entity_id=dict(required=True),
+            label=dict(required=True),
+            check_type=dict(required=True),
+            monitoring_zones_poll=dict(),
+            target_hostname=dict(),
+            target_alias=dict(),
+            details=dict(type='dict', default={}),
+            disabled=dict(type='bool', default=False),
+            metadata=dict(type='dict', default={}),
+            period=dict(type='int'),
+            timeout=dict(type='int'),
+            state=dict(default='present', choices=['present', 'absent'])
+        )
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        required_together=rax_required_together()
+    )
+
+    if not HAS_PYRAX:
+        module.fail_json(msg='pyrax is required for this module')
+
+    entity_id = module.params.get('entity_id')
+    label = module.params.get('label')
+    check_type = module.params.get('check_type')
+    monitoring_zones_poll = module.params.get('monitoring_zones_poll')
+    target_hostname = module.params.get('target_hostname')
+    target_alias = module.params.get('target_alias')
+    details = module.params.get('details')
+    disabled = module.boolean(module.params.get('disabled'))
+    metadata = module.params.get('metadata')
+    period = module.params.get('period')
+    timeout = module.params.get('timeout')
+
+    state = module.params.get('state')
+
+    setup_rax_module(module, pyrax)
+
+    cloud_check(module, state, entity_id, label, check_type,
+                monitoring_zones_poll, target_hostname, target_alias, details,
+                disabled, metadata, period, timeout)
+
+
+# Import module snippets
+from ansible.module_utils.basic import *
+from ansible.module_utils.rax import *
+
+# Invoke the module.
+main()

cloud/rackspace/rax_mon_entity.py

@@ -0,0 +1,192 @@
+#!/usr/bin/python
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
+DOCUMENTATION = '''
+---
+module: rax_mon_entity
+short_description: Create or delete a Rackspace Cloud Monitoring entity
+description:
+- Create or delete a Rackspace Cloud Monitoring entity, which represents a device
+  to monitor. Entities associate checks and alarms with a target system and
+  provide a convenient, centralized place to store IP addresses. Rackspace
+  monitoring module flow | *rax_mon_entity* -> rax_mon_check ->
+  rax_mon_notification -> rax_mon_notification_plan -> rax_mon_alarm
+version_added: "1.9"
+options:
+  label:
+    description:
+    - Defines a name for this entity. Must be a non-empty string between 1 and
+      255 characters long.
+    required: true
+  state:
+    description:
+    - Ensure that an entity with this C(name) exists or does not exist.
+    choices: ["present", "absent"]
+  agent_id:
+    description:
+    - Rackspace monitoring agent on the target device to which this entity is
+      bound. Necessary to collect C(agent.) rax_mon_checks against this entity.
+  named_ip_addresses:
+    description:
+    - Hash of IP addresses that may be referenced by name by rax_mon_checks
+      added to this entity. Must be a dictionary of with keys that are names
+      between 1 and 64 characters long, and values that are valid IPv4 or IPv6
+      addresses.
+  metadata:
+    description:
+    - Hash of arbitrary C(name), C(value) pairs that are passed to associated
+      rax_mon_alarms. Names and values must all be between 1 and 255 characters
+      long.
+author: Ash Wilson
+extends_documentation_fragment: rackspace.openstack
+'''
+
+EXAMPLES = '''
+- name: Entity example
+  gather_facts: False
+  hosts: local
+  connection: local
+  tasks:
+  - name: Ensure an entity exists
+    rax_mon_entity:
+      credentials: ~/.rax_pub
+      state: present
+      label: my_entity
+      named_ip_addresses:
+        web_box: 192.168.0.10
+        db_box: 192.168.0.11
+      meta:
+        hurf: durf
+    register: the_entity
+'''
+
+try:
+    import pyrax
+    HAS_PYRAX = True
+except ImportError:
+    HAS_PYRAX = False
+
+def cloud_monitoring(module, state, label, agent_id, named_ip_addresses,
+                     metadata):
+
+    if len(label) < 1 or len(label) > 255:
+        module.fail_json(msg='label must be between 1 and 255 characters long')
+
+    changed = False
+
+    cm = pyrax.cloud_monitoring
+    if not cm:
+        module.fail_json(msg='Failed to instantiate client. This typically '
+                             'indicates an invalid region or an incorrectly '
+                             'capitalized region name.')
+
+    existing = []
+    for entity in cm.list_entities():
+        if label == entity.label:
+            existing.append(entity)
+
+    entity = None
+
+    if existing:
+        entity = existing[0]
+
+    if state == 'present':
+        should_update = False
+        should_delete = False
+        should_create = False
+
+        if len(existing) > 1:
+            module.fail_json(msg='%s existing entities have the label %s.' %
+                                 (len(existing), label))
+
+        if entity:
+            if named_ip_addresses and named_ip_addresses != entity.ip_addresses:
+                should_delete = should_create = True
+
+            # Change an existing Entity, unless there's nothing to do.
+            should_update = agent_id and agent_id != entity.agent_id or \
+                (metadata and metadata != entity.metadata)
+
+            if should_update and not should_delete:
+                entity.update(agent_id, metadata)
+                changed = True
+
+            if should_delete:
+                entity.delete()
+        else:
+            should_create = True
+
+        if should_create:
+            # Create a new Entity.
+            entity = cm.create_entity(label=label, agent=agent_id,
+                                      ip_addresses=named_ip_addresses,
+                                      metadata=metadata)
+            changed = True
+    else:
+        # Delete the existing Entities.
+        for e in existing:
+            e.delete()
+            changed = True
+
+    if entity:
+        entity_dict = {
+            "id": entity.id,
+            "name": entity.name,
+            "agent_id": entity.agent_id,
+        }
+        module.exit_json(changed=changed, entity=entity_dict)
+    else:
+        module.exit_json(changed=changed)
+
+def main():
+    argument_spec = rax_argument_spec()
+    argument_spec.update(
+        dict(
+            state=dict(default='present', choices=['present', 'absent']),
+            label=dict(required=True),
+            agent_id=dict(),
+            named_ip_addresses=dict(type='dict', default={}),
+            metadata=dict(type='dict', default={})
+        )
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        required_together=rax_required_together()
+    )
+
+    if not HAS_PYRAX:
+        module.fail_json(msg='pyrax is required for this module')
+
+    state = module.params.get('state')
+
+    label = module.params.get('label')
+    agent_id = module.params.get('agent_id')
+    named_ip_addresses = module.params.get('named_ip_addresses')
+    metadata = module.params.get('metadata')
+
+    setup_rax_module(module, pyrax)
+
+    cloud_monitoring(module, state, label, agent_id, named_ip_addresses, metadata)
+
+# Import module snippets
+from ansible.module_utils.basic import *
+from ansible.module_utils.rax import *
+
+# Invoke the module.
+main()

cloud/rackspace/rax_mon_notification.py

@@ -0,0 +1,176 @@
+#!/usr/bin/python
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
+DOCUMENTATION = '''
+---
+module: rax_mon_notification
+short_description: Create or delete a Rackspace Cloud Monitoring notification.
+description:
+- Create or delete a Rackspace Cloud Monitoring notification that specifies a
+  channel that can be used to communicate alarms, such as email, webhooks, or
+  PagerDuty. Rackspace monitoring module flow | rax_mon_entity -> rax_mon_check ->
+  *rax_mon_notification* -> rax_mon_notification_plan -> rax_mon_alarm
+version_added: "1.9"
+options:
+  state:
+    description:
+    - Ensure that the notification with this C(label) exists or does not exist.
+    choices: ['present', 'absent']
+  label:
+    description:
+    - Defines a friendly name for this notification. String between 1 and 255
+      characters long.
+    required: true
+  notification_type:
+    description:
+    - A supported notification type.
+    choices: ["webhook", "email", "pagerduty"]
+    required: true
+  details:
+    description:
+    - Dictionary of key-value pairs used to initialize the notification.
+      Required keys and meanings vary with notification type. See
+      http://docs.rackspace.com/cm/api/v1.0/cm-devguide/content/
+      service-notification-types-crud.html for details.
+    required: true
+author: Ash Wilson
+extends_documentation_fragment: rackspace.openstack
+'''
+
+EXAMPLES = '''
+- name: Monitoring notification example
+  gather_facts: False
+  hosts: local
+  connection: local
+  tasks:
+  - name: Email me when something goes wrong.
+    rax_mon_entity:
+      credentials: ~/.rax_pub
+      label: omg
+      type: email
+      details:
+        address: me@mailhost.com
+    register: the_notification
+'''
+
+try:
+    import pyrax
+    HAS_PYRAX = True
+except ImportError:
+    HAS_PYRAX = False
+
+def notification(module, state, label, notification_type, details):
+
+    if len(label) < 1 or len(label) > 255:
+        module.fail_json(msg='label must be between 1 and 255 characters long')
+
+    changed = False
+    notification = None
+
+    cm = pyrax.cloud_monitoring
+    if not cm:
+        module.fail_json(msg='Failed to instantiate client. This typically '
+                             'indicates an invalid region or an incorrectly '
+                             'capitalized region name.')
+
+    existing = []
+    for n in cm.list_notifications():
+        if n.label == label:
+            existing.append(n)
+
+    if existing:
+        notification = existing[0]
+
+    if state == 'present':
+        should_update = False
+        should_delete = False
+        should_create = False
+
+        if len(existing) > 1:
+            module.fail_json(msg='%s existing notifications are labelled %s.' %
+                                 (len(existing), label))
+
+        if notification:
+            should_delete = (notification_type != notification.type)
+
+            should_update = (details != notification.details)
+
+            if should_update and not should_delete:
+                notification.update(details=notification.details)
+                changed = True
+
+            if should_delete:
+                notification.delete()
+        else:
+            should_create = True
+
+        if should_create:
+            notification = cm.create_notification(notification_type,
+                                                  label=label, details=details)
+            changed = True
+    else:
+        for n in existing:
+            n.delete()
+            changed = True
+
+    if notification:
+        notification_dict = {
+            "id": notification.id,
+            "type": notification.type,
+            "label": notification.label,
+            "details": notification.details
+        }
+        module.exit_json(changed=changed, notification=notification_dict)
+    else:
+        module.exit_json(changed=changed)
+
+def main():
+    argument_spec = rax_argument_spec()
+    argument_spec.update(
+        dict(
+            state=dict(default='present', choices=['present', 'absent']),
+            label=dict(required=True),
+            notification_type=dict(required=True, choices=['webhook', 'email', 'pagerduty']),
+            details=dict(required=True, type='dict')
+        )
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        required_together=rax_required_together()
+    )
+
+    if not HAS_PYRAX:
+        module.fail_json(msg='pyrax is required for this module')
+
+    state = module.params.get('state')
+
+    label = module.params.get('label')
+    notification_type = module.params.get('notification_type')
+    details = module.params.get('details')
+
+    setup_rax_module(module, pyrax)
+
+    notification(module, state, label, notification_type, details)
+
+# Import module snippets
+from ansible.module_utils.basic import *
+from ansible.module_utils.rax import *
+
+# Invoke the module.
+main()

cloud/rackspace/rax_mon_notification_plan.py

@@ -0,0 +1,181 @@
+#!/usr/bin/python
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
+DOCUMENTATION = '''
+---
+module: rax_mon_notification_plan
+short_description: Create or delete a Rackspace Cloud Monitoring notification
+                   plan.
+description:
+- Create or delete a Rackspace Cloud Monitoring notification plan by
+  associating existing rax_mon_notifications with severity levels. Rackspace
+  monitoring module flow | rax_mon_entity -> rax_mon_check ->
+  rax_mon_notification -> *rax_mon_notification_plan* -> rax_mon_alarm
+version_added: "1.9"
+options:
+  state:
+    description:
+    - Ensure that the notification plan with this C(label) exists or does not
+      exist.
+    choices: ['present', 'absent']
+  label:
+    description:
+    - Defines a friendly name for this notification plan. String between 1 and
+      255 characters long.
+    required: true
+  critical_state:
+    description:
+    - Notification list to use when the alarm state is CRITICAL. Must be an
+      array of valid rax_mon_notification ids.
+  warning_state:
+    description:
+    - Notification list to use when the alarm state is WARNING. Must be an array
+      of valid rax_mon_notification ids.
+  ok_state:
+    description:
+    - Notification list to use when the alarm state is OK. Must be an array of
+      valid rax_mon_notification ids.
+author: Ash Wilson
+extends_documentation_fragment: rackspace.openstack
+'''
+
+EXAMPLES = '''
+- name: Example notification plan
+  gather_facts: False
+  hosts: local
+  connection: local
+  tasks:
+  - name: Establish who gets called when.
+    rax_mon_notification_plan:
+      credentials: ~/.rax_pub
+      state: present
+      label: defcon1
+      critical_state:
+      - "{{ everyone['notification']['id'] }}"
+      warning_state:
+      - "{{ opsfloor['notification']['id'] }}"
+    register: defcon1
+'''
+
+try:
+    import pyrax
+    HAS_PYRAX = True
+except ImportError:
+    HAS_PYRAX = False
+
+def notification_plan(module, state, label, critical_state, warning_state, ok_state):
+
+    if len(label) < 1 or len(label) > 255:
+        module.fail_json(msg='label must be between 1 and 255 characters long')
+
+    changed = False
+    notification_plan = None
+
+    cm = pyrax.cloud_monitoring
+    if not cm:
+        module.fail_json(msg='Failed to instantiate client. This typically '
+                             'indicates an invalid region or an incorrectly '
+                             'capitalized region name.')
+
+    existing = []
+    for n in cm.list_notification_plans():
+        if n.label == label:
+            existing.append(n)
+
+    if existing:
+        notification_plan = existing[0]
+
+    if state == 'present':
+        should_create = False
+        should_delete = False
+
+        if len(existing) > 1:
+            module.fail_json(msg='%s notification plans are labelled %s.' %
+                                 (len(existing), label))
+
+        if notification_plan:
+            should_delete = (critical_state and critical_state != notification_plan.critical_state) or \
+                (warning_state and warning_state != notification_plan.warning_state) or \
+                (ok_state and ok_state != notification_plan.ok_state)
+
+            if should_delete:
+                notification_plan.delete()
+                should_create = True
+        else:
+            should_create = True
+
+        if should_create:
+            notification_plan = cm.create_notification_plan(label=label,
+                                                            critical_state=critical_state,
+                                                            warning_state=warning_state,
+                                                            ok_state=ok_state)
+            changed = True
+    else:
+        for np in existing:
+            np.delete()
+            changed = True
+
+    if notification_plan:
+        notification_plan_dict = {
+            "id": notification_plan.id,
+            "critical_state": notification_plan.critical_state,
+            "warning_state": notification_plan.warning_state,
+            "ok_state": notification_plan.ok_state,
+            "metadata": notification_plan.metadata
+        }
+        module.exit_json(changed=changed, notification_plan=notification_plan_dict)
+    else:
+        module.exit_json(changed=changed)
+
+def main():
+    argument_spec = rax_argument_spec()
+    argument_spec.update(
+        dict(
+            state=dict(default='present', choices=['present', 'absent']),
+            label=dict(required=True),
+            critical_state=dict(type='list'),
+            warning_state=dict(type='list'),
+            ok_state=dict(type='list')
+        )
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        required_together=rax_required_together()
+    )
+
+    if not HAS_PYRAX:
+        module.fail_json(msg='pyrax is required for this module')
+
+    state = module.params.get('state')
+
+    label = module.params.get('label')
+    critical_state = module.params.get('critical_state')
+    warning_state = module.params.get('warning_state')
+    ok_state = module.params.get('ok_state')
+
+    setup_rax_module(module, pyrax)
+
+    notification_plan(module, state, label, critical_state, warning_state, ok_state)
+
+# Import module snippets
+from ansible.module_utils.basic import *
+from ansible.module_utils.rax import *
+
+# Invoke the module.
+main()