Add sensu_handler Ansible module

This provides a sensu_handler module in order to be able to dynamically
configure a Sensu handler.

lib/ansible/modules/monitoring/sensu_handler.py

@@ -0,0 +1,285 @@
+#!/usr/bin/python
+
+# (c) 2017, Red Hat 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.0',
+    'status': ['preview'],
+    'supported_by': 'community'
+}
+
+DOCUMENTATION = '''
+---
+module: sensu_handler
+author: "David Moreau Simard (@dmsimard)"
+short_description: Manages Sensu handler configuration
+version_added: 2.4
+description:
+  - Manages Sensu handler configuration
+  - 'For more information, refer to the Sensu documentation: U(https://sensuapp.org/docs/latest/reference/handlers.html)'
+options:
+  state:
+    description:
+      - Whether the handler should be present or not
+    choices: [ 'present', 'absent' ]
+    required: False
+    default: present
+  name:
+    description:
+      - A unique name for the handler. The name cannot contain special characters or spaces.
+    required: True
+    default: null
+  type:
+    description:
+      - The handler type
+    choices: [ 'pipe', 'tcp', 'udp', 'transport', 'set' ]
+    required: True
+    default: null
+  filter:
+    description:
+      - The Sensu event filter (name) to use when filtering events for the handler.
+    required: False
+    default: null
+  filters:
+    description:
+      - An array of Sensu event filters (names) to use when filtering events for the handler.
+      - Each array item must be a string.
+    required: False
+    default: null
+  severities:
+    description:
+      - An array of check result severities the handler will handle.
+      - 'NOTE: event resolution bypasses this filtering.'
+    choices: [ 'warning', 'critical', 'unknown' ]
+    required: False
+    default: null
+  mutator:
+    description:
+      - The Sensu event mutator (name) to use to mutate event data for the handler.
+    required: False
+    default: null
+  timeout:
+    description:
+      - The handler execution duration timeout in seconds (hard stop).
+      - Only used by pipe and tcp handler types.
+    required: False
+    default: 10
+  handle_silenced:
+    description:
+      - If events matching one or more silence entries should be handled.
+    required: False
+    default: False
+  handle_flapping:
+    description:
+      - If events in the flapping state should be handled.
+    required: False
+    default: False
+  command:
+    description:
+      - The handler command to be executed.
+      - The event data is passed to the process via STDIN.
+      - 'NOTE: the command attribute is only required for Pipe handlers (i.e. handlers configured with "type": "pipe").'
+    required: False
+    default: null
+  socket:
+    description:
+      - The socket definition scope, used to configure the TCP/UDP handler socket.
+      - 'NOTE: the socket attribute is only required for TCP/UDP handlers (i.e. handlers configured with "type": "tcp" or "type": "udp").'
+    required: False
+    default: null
+  pipe:
+    description:
+      - The pipe definition scope, used to configure the Sensu transport pipe.
+      - 'NOTE: the pipe attribute is only required for Transport handlers (i.e. handlers configured with "type": "transport").'
+    required: False
+    default: null
+  handlers:
+    description:
+      - An array of Sensu event handlers (names) to use for events using the handler set.
+      - Each array item must be a string.
+      - 'NOTE: the handlers attribute is only required for handler sets (i.e. handlers configured with "type": "set").'
+    required: True
+    default: null
+notes:
+  - Check mode is supported
+requirements: [ ]
+'''
+
+EXAMPLES = '''
+# Configure a handler that sends event data as STDIN (pipe)
+- name: Configure IRC Sensu handler
+  sensu_handler:
+    name: "irc_handler"
+    type: "pipe"
+    command: "/usr/local/bin/notify-irc.sh"
+    severities:
+      - "ok"
+      - "critical"
+      - "warning"
+      - "unknown"
+    timeout: 15
+  notify:
+    - Restart sensu-client
+    - Restart sensu-server
+
+# Delete a handler
+- name: Delete IRC Sensu handler
+  sensu_handler:
+    name: "irc_handler"
+    state: "absent"
+
+# Example of a TCP handler
+- name: Configure TCP Sensu handler
+  sensu_handler:
+    name: "tcp_handler"
+    type: "tcp"
+    timeout: 30
+    socket:
+      host: "10.0.1.99"
+      port: 4444
+  register: handler
+  notify:
+    - Restart sensu-client
+    - Restart sensu-server
+
+- name: Secure Sensu handler configuration file
+  file:
+    path: "{{ handler['file'] }}"
+    owner: "sensu"
+    group: "sensu"
+    mode: "0600"
+'''
+
+RETURN = '''
+config:
+  description: Effective handler configuration, when state is present
+  returned: success
+  type: dict
+  sample: {'name': 'irc', 'type': 'pipe', 'command': '/usr/local/bin/notify-irc.sh'}
+file:
+  description: Path to the handler configuration file
+  returned: success
+  type: string
+  sample: "/etc/sensu/conf.d/handlers/irc.json"
+name:
+  description: Name of the handler
+  returned: success
+  type: string
+  sample: "irc"
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+import json
+import os
+
+
+def main():
+    module = AnsibleModule(
+        supports_check_mode=True,
+        argument_spec=dict(
+            state=dict(type='str', required=False, choices=['present', 'absent'], default='present'),
+            name=dict(type='str', required=True),
+            type=dict(type='str', required=False, choices=['pipe', 'tcp', 'udp', 'transport', 'set']),
+            filter=dict(type='str', required=False),
+            filters=dict(type='list', required=False),
+            severities=dict(type='list', required=False),
+            mutator=dict(type='str', required=False),
+            timeout=dict(type='int', required=False, default=10),
+            handle_silenced=dict(type='bool', required=False, default=False),
+            handle_flapping=dict(type='bool', required=False, default=False),
+            command=dict(type='str', required=False),
+            socket=dict(type='dict', required=False),
+            pipe=dict(type='dict', required=False),
+            handlers=dict(type='list', required=False),
+        ),
+        required_if=[
+            ['state', 'present', ['type']],
+            ['type', 'pipe', ['command']],
+            ['type', 'tcp', ['socket']],
+            ['type', 'udp', ['socket']],
+            ['type', 'transport', ['pipe']],
+            ['type', 'set', ['handlers']]
+        ]
+    )
+
+    state = module.params['state']
+    name = module.params['name']
+    path = '/etc/sensu/conf.d/handlers/{0}.json'.format(name)
+
+    if state == 'absent':
+        if os.path.exists(path):
+            if module.check_mode:
+                msg = '{path} would have been deleted'.format(path=path)
+                module.exit_json(msg=msg, changed=True)
+            else:
+                try:
+                    os.remove(path)
+                    msg = '{path} deleted successfully'.format(path=path)
+                    module.exit_json(msg=msg, changed=True)
+                except OSError as e:
+                    msg = 'Exception when trying to delete {path}: {exception}'
+                    module.fail_json(
+                        msg=msg.format(path=path, exception=str(e)))
+        else:
+            # Idempotency: it's okay if the file doesn't exist
+            msg = '{path} already does not exist'.format(path=path)
+            module.exit_json(msg=msg)
+
+    # Build handler configuration from module arguments
+    config = {'handlers': {name: {}}}
+    args = ['type', 'filter', 'filters', 'severities', 'mutator', 'timeout',
+            'handle_silenced', 'handle_flapping', 'command', 'socket',
+            'pipe', 'handlers']
+
+    for arg in args:
+        if arg in module.params and module.params[arg] is not None:
+            config['handlers'][name][arg] = module.params[arg]
+
+    # Load the current config, if there is one, so we can compare
+    current_config = None
+    try:
+        current_config = json.load(open(path, 'r'))
+    except (IOError, ValueError):
+        # File either doesn't exist or it's invalid JSON
+        pass
+
+    if current_config is not None and current_config == config:
+        # Config is the same, let's not change anything
+        module.exit_json(msg='Handler configuration is already up to date',
+                         config=config['handlers'][name],
+                         file=path,
+                         name=name)
+
+    # Validate that directory exists before trying to write to it
+    if not module.check_mode and not os.path.exists(os.path.dirname(path)):
+        try:
+            os.makedirs(os.path.dirname(path))
+        except OSError as e:
+            module.fail_json(msg='Unable to create {0}: {1}'.format(os.path.dirname(path),
+                                                                    str(e)))
+
+    if module.check_mode:
+        module.exit_json(msg='Handler configuration would have been updated',
+                         changed=True,
+                         config=config['handlers'][name],
+                         file=path,
+                         name=name)
+
+    try:
+        with open(path, 'w') as handler:
+            handler.write(json.dumps(config, indent=4))
+            module.exit_json(msg='Handler configuration updated',
+                             changed=True,
+                             config=config['handlers'][name],
+                             file=path,
+                             name=name)
+    except (OSError, IOError) as e:
+        module.fail_json(msg='Unable to write file {0}: {1}'.format(path,
+                                                                    str(e)))
+
+if __name__ == '__main__':
+    main()

test/integration/targets/sensu_handler/aliases

@@ -0,0 +1 @@
+posix/ci/group1

test/integration/targets/sensu_handler/tasks/main.yml

@@ -0,0 +1,120 @@
+- name: Creating a handler if the directory doesn't exist should work
+  sensu_handler:
+    name: "handler"
+    type: "pipe"
+    command: "/bin/bash"
+    state: "present"
+
+- name: Insert junk JSON in a handlers file
+  lineinfile:
+    state: "present"
+    create: "yes"
+    path: "/etc/sensu/conf.d/handlers/handler.json"
+    line: "{'foo' = bar}"
+
+- name: Configure a handler with an existing invalid file
+  sensu_handler:
+    name: "handler"
+    type: "pipe"
+    command: "/bin/bash"
+    state: "present"
+  register: handler
+
+- name: Configure a handler (again)
+  sensu_handler:
+    name: "handler"
+    type: "pipe"
+    command: "/bin/bash"
+    state: "present"
+  register: handler_twice
+
+- name: Retrieve configuration file stat
+  stat:
+    path: "{{ handler['file'] }}"
+  register: handler_stat
+
+- name: Assert that handler data was set successfully and properly
+  assert:
+    that:
+      - "handler | success"
+      - "handler | changed"
+      - "handler_twice | success"
+      - "not handler_twice | changed"
+      - "handler_stat.stat.exists == true"
+      - "handler['name'] == 'handler'"
+      - "handler['file'] == '/etc/sensu/conf.d/handlers/handler.json'"
+      - "handler['config']['type'] == 'pipe'"
+      - "handler['config']['command'] == '/bin/bash'"
+      - "handler['config']['timeout'] == 10"
+      - "handler['config']['handle_flapping'] == false"
+      - "handler['config']['handle_silenced'] == false"
+
+- name: Assert that the handler configuration file is actually configured properly
+  vars:
+    config: "{{ lookup('file', handler['file']) | from_json }}"
+  assert:
+    that:
+      - "'handler' in config['handlers']"
+      - "config['handlers']['handler']['type'] == 'pipe'"
+      - "config['handlers']['handler']['command'] == '/bin/bash'"
+      - "config['handlers']['handler']['timeout'] == 10"
+      - "config['handlers']['handler']['handle_flapping'] == false"
+      - "config['handlers']['handler']['handle_silenced'] == false"
+
+- name: Delete Sensu handler configuration
+  sensu_handler:
+    name: "handler"
+    state: "absent"
+  register: handler_delete
+
+- name: Delete Sensu handler configuration (again)
+  sensu_handler:
+    name: "handler"
+    state: "absent"
+  register: handler_delete_twice
+
+- name: Retrieve configuration file stat
+  stat:
+    path: "{{ handler['file'] }}"
+  register: handler_stat
+
+- name: Assert that handler deletion was successful
+  assert:
+    that:
+      - "handler_delete | success"
+      - "handler_delete | changed"
+      - "handler_delete_twice | success"
+      - "not handler_delete_twice | changed"
+      - "handler_stat.stat.exists == false"
+
+- name: Configuring a handler without a name should fail
+  sensu_handler:
+    type: "pipe"
+    command: "/bin/bash"
+  register: failure
+  ignore_errors: true
+
+- name: Assert that configuring a handler without a name fails
+  assert:
+    that:
+      - failure | failed
+      - "'required arguments: name' in failure['msg']"
+
+- name: Configuring a handler without a type should fail
+  sensu_handler:
+    name: "pipe"
+    command: "/bin/bash"
+  register: failure
+  ignore_errors: true
+
+- name: Assert that configuring a handler without a type fails
+  assert:
+    that:
+      - failure | failed
+      - "'the following are missing: type' in failure['msg']"
+
+- include: pipe.yml
+- include: tcp.yml
+- include: udp.yml
+- include: set.yml
+- include: transport.yml

test/integration/targets/sensu_handler/tasks/pipe.yml

@@ -0,0 +1,20 @@
+# Note: Pipe handlers are also tested and used as part of basic main.yml coverage
+- name: Configuring a handler with missing pipe parameters should fail
+  sensu_handler:
+    name: "pipe"
+    type: "pipe"
+  register: failure
+  ignore_errors: true
+
+- name: Assert that configuring a handler with missing pipe parameters fails
+  assert:
+    that:
+      - failure | failed
+      - "'the following are missing: command' in failure['msg']"
+
+- name: Configure a handler with pipe parameters
+  sensu_handler:
+    name: "pipe"
+    type: "pipe"
+    command: "/bin/bash"
+  register: handler

test/integration/targets/sensu_handler/tasks/set.yml

@@ -0,0 +1,49 @@
+- name: Configuring a handler with missing set parameters should fail
+  sensu_handler:
+    name: "set"
+    type: "set"
+  register: failure
+  ignore_errors: true
+
+- name: Assert that configuring a handler with missing set parameters fails
+  assert:
+    that:
+      - failure | failed
+      - "'the following are missing: handlers' in failure['msg']"
+
+- name: Configure a set handler
+  sensu_handler:
+    name: "set"
+    type: "set"
+    handlers:
+      - anotherhandler
+  register: handler
+
+- name: Retrieve configuration file stat
+  stat:
+    path: "{{ handler['file'] }}"
+  register: handler_stat
+
+- name: Validate set handler return data
+  assert:
+    that:
+      - "handler | success"
+      - "handler | changed"
+      - "handler_stat.stat.exists == true"
+      - "handler['name'] == 'set'"
+      - "handler['file'] == '/etc/sensu/conf.d/handlers/set.json'"
+      - "handler['config']['type'] == 'set'"
+      - "'anotherhandler' in handler['config']['handlers']"
+      - "handler['config']['handle_flapping'] == false"
+      - "handler['config']['handle_silenced'] == false"
+
+- name: Assert that the handler configuration file is actually configured properly
+  vars:
+    config: "{{ lookup('file', handler['file']) | from_json }}"
+  assert:
+    that:
+      - "'set' in config['handlers']"
+      - "config['handlers']['set']['type'] == 'set'"
+      - "'anotherhandler' in config['handlers']['set']['handlers']"
+      - "config['handlers']['set']['handle_flapping'] == false"
+      - "config['handlers']['set']['handle_silenced'] == false"

test/integration/targets/sensu_handler/tasks/tcp.yml

@@ -0,0 +1,52 @@
+- name: Configuring a handler with missing tcp parameters should fail
+  sensu_handler:
+    name: "tcp"
+    type: "tcp"
+  register: failure
+  ignore_errors: true
+
+- name: Assert that configuring a handler with missing tcp parameters fails
+  assert:
+    that:
+      - failure | failed
+      - "'the following are missing: socket' in failure['msg']"
+
+- name: Configure a tcp handler
+  sensu_handler:
+    name: "tcp"
+    type: "tcp"
+    socket:
+      host: 127.0.0.1
+      port: 8000
+  register: handler
+
+- name: Retrieve configuration file stat
+  stat:
+    path: "{{ handler['file'] }}"
+  register: handler_stat
+
+- name: Validate tcp handler return data
+  assert:
+    that:
+      - "handler | success"
+      - "handler | changed"
+      - "handler_stat.stat.exists == true"
+      - "handler['name'] == 'tcp'"
+      - "handler['file'] == '/etc/sensu/conf.d/handlers/tcp.json'"
+      - "handler['config']['type'] == 'tcp'"
+      - "handler['config']['socket']['host'] == '127.0.0.1'"
+      - "handler['config']['socket']['port'] == 8000"
+      - "handler['config']['handle_flapping'] == false"
+      - "handler['config']['handle_silenced'] == false"
+
+- name: Assert that the handler configuration file is actually configured properly
+  vars:
+    config: "{{ lookup('file', handler['file']) | from_json }}"
+  assert:
+    that:
+      - "'tcp' in config['handlers']"
+      - "config['handlers']['tcp']['type'] == 'tcp'"
+      - "config['handlers']['tcp']['socket']['host'] == '127.0.0.1'"
+      - "config['handlers']['tcp']['socket']['port'] == 8000"
+      - "config['handlers']['tcp']['handle_flapping'] == false"
+      - "config['handlers']['tcp']['handle_silenced'] == false"

test/integration/targets/sensu_handler/tasks/transport.yml

@@ -0,0 +1,52 @@
+- name: Configuring a handler with missing transport parameters should fail
+  sensu_handler:
+    name: "transport"
+    type: "transport"
+  register: failure
+  ignore_errors: true
+
+- name: Assert that configuring a handler with missing transport parameters fails
+  assert:
+    that:
+      - failure | failed
+      - "'the following are missing: pipe' in failure['msg']"
+
+- name: Configure a transport handler
+  sensu_handler:
+    name: "transport"
+    type: "transport"
+    pipe:
+      type: "topic"
+      name: "transport_handler"
+  register: handler
+
+- name: Retrieve configuration file stat
+  stat:
+    path: "{{ handler['file'] }}"
+  register: handler_stat
+
+- name: Validate transport handler return data
+  assert:
+    that:
+      - "handler | success"
+      - "handler | changed"
+      - "handler_stat.stat.exists == true"
+      - "handler['name'] == 'transport'"
+      - "handler['file'] == '/etc/sensu/conf.d/handlers/transport.json'"
+      - "handler['config']['type'] == 'transport'"
+      - "handler['config']['pipe']['type'] == 'topic'"
+      - "handler['config']['pipe']['name'] == 'transport_handler'"
+      - "handler['config']['handle_flapping'] == false"
+      - "handler['config']['handle_silenced'] == false"
+
+- name: Assert that the handler configuration file is actually configured properly
+  vars:
+    config: "{{ lookup('file', handler['file']) | from_json }}"
+  assert:
+    that:
+      - "'transport' in config['handlers']"
+      - "config['handlers']['transport']['type'] == 'transport'"
+      - "config['handlers']['transport']['pipe']['type'] == 'topic'"
+      - "config['handlers']['transport']['pipe']['name'] == 'transport_handler'"
+      - "config['handlers']['transport']['handle_flapping'] == false"
+      - "config['handlers']['transport']['handle_silenced'] == false"

test/integration/targets/sensu_handler/tasks/udp.yml

@@ -0,0 +1,52 @@
+- name: Configuring a handler with missing udp parameters should fail
+  sensu_handler:
+    name: "udp"
+    type: "udp"
+  register: failure
+  ignore_errors: true
+
+- name: Assert that configuring a handler with missing udp parameters fails
+  assert:
+    that:
+      - failure | failed
+      - "'the following are missing: socket' in failure['msg']"
+
+- name: Configure a udp handler
+  sensu_handler:
+    name: "udp"
+    type: "udp"
+    socket:
+      host: 127.0.0.1
+      port: 8000
+  register: handler
+
+- name: Retrieve configuration file stat
+  stat:
+    path: "{{ handler['file'] }}"
+  register: handler_stat
+
+- name: Validate udp handler return data
+  assert:
+    that:
+      - "handler | success"
+      - "handler | changed"
+      - "handler_stat.stat.exists == true"
+      - "handler['name'] == 'udp'"
+      - "handler['file'] == '/etc/sensu/conf.d/handlers/udp.json'"
+      - "handler['config']['type'] == 'udp'"
+      - "handler['config']['socket']['host'] == '127.0.0.1'"
+      - "handler['config']['socket']['port'] == 8000"
+      - "handler['config']['handle_flapping'] == false"
+      - "handler['config']['handle_silenced'] == false"
+
+- name: Assert that the handler configuration file is actually configured properly
+  vars:
+    config: "{{ lookup('file', handler['file']) | from_json }}"
+  assert:
+    that:
+      - "'udp' in config['handlers']"
+      - "config['handlers']['udp']['type'] == 'udp'"
+      - "config['handlers']['udp']['socket']['host'] == '127.0.0.1'"
+      - "config['handlers']['udp']['socket']['port'] == 8000"
+      - "config['handlers']['udp']['handle_flapping'] == false"
+      - "config['handlers']['udp']['handle_silenced'] == false"