Sensu Ansible Handler

• Overview
• Usage example(s)
• Example output
• Configuration
  • Handler configuration
  • Handler configuration
• References
  • Documentation
  • Development & Troubleshooting
  • Roadmap

Overview

A Sensu Go Handler for launching Ansible Tower Job Templates for automated
remediation.

Job Template Requests

Checks making use of this handler may specify an optional set of Ansible Tower job template requests to run for matching Sensu event occurrence and severity conditions using a check annotation io.sensu.ansible.config.actions. The value of the annotation is a json array of requests. Each request can include:

• template_id : the job template id.
• template_name : the name of the job template, used if template_id is not specified
• inventory_id : the inventory id.
• inventory_name : the name of the inventory, used if inventory_id is not specified
• limit : inventory limit
• occurrences: array of event occurrence values to match
• severities: array of event severity values to match

All request attributes are optional, and under specified requests will take missing values from the associated handler commandline or envvar arguments. Please review the handler usage information and look below for a check configuration example.

Enterprise Plugin

The Sensu Go Ansible Handler is an Enterprise plugin that requires a valid Sensu license to run.
Sensu Go >= 5.21 will add the SENSU_LICENSE_FILE environment variable to the handler execution.
To run the plugin independently of Sensu (ex. test/dev), you must set the env var:

SENSU_LICENSE_FILE=$(sensuctl license info --format json)

Usage example(s)

$ sensuctl asset add sensu/sensu-ansible-handler
$ sensuctl handler create ansible --type pipe \
  --runtime-assets sensu/sensu-ansible-handler \
  --command "sensu-ansible-handler --host 127.0.0.1 --output-log-file=/var/log/sensu/sensu-backend/sensu-ansible-handler.log" \
  --timeout 10 --env-vars "ANSIBLE_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

NOTE: please take care to modify the --host and --output-log-file
configuration flags and the ANSIBLE_TOKEN environment variable, as needed.

For more information, please consult the --help output:

$ sensu-ansible-handler --help
The Sensu Go Ansible Tower handler for automated remediation.

Usage:
  sensu-ansible-handler [flags]
  sensu-ansible-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

Flags:
  -h, --help                     help for sensu-ansible-handler
  -H, --host string              The Ansible Tower API hostname or IP address.
                                   Can also be set via the $ANSIBLE_HOST environment variable.
                                  (default "127.0.0.1")
      --insecure-skip-tls-verify skip TLS certificate verification (not recommended!)
  -i, --inventory string         The Ansible Tower Inventory name (includes Smart Inventories), used to lookup an Inventory ID.
                                   Can also be set via $ANSIBLE_INVENTORY_NAME.
                                   Only used if job template request 'inventory_name' is not set.
                                   Ignored if --inventory-id or $ANSIBLE_INVENTORY_ID are set.
                                 
  -I, --inventory-id int         The Ansible Tower Inventory ID (includes Smart Inventories).
                                   Can also be set via the $ANSIBLE_INVENTORY_ID environment variable.
                                   Only used if job template request 'inventory_id' is not set.
                                 
  -L, --inventory-limit string   The Ansible Tower Inventory limit (defaults to the Sensu entity name).
                                  Can also be set via the $ANSIBLE_INVENTORY_LIMIT environment variable.
                                   Only used if job template request 'limit' is not set.
                                   If no limit is set, entity name from event is used.
                                 
  -j, --job-template string      The Ansible Tower Job Template name, used to lookup a Job Template ID.
                                   Can also be set via $ANSIBLE_JOB_TEMPLATE_NAME.
                                   Only used if job template request 'template_name' is not set.
                                   Ignored if if --job-template-id or $ANSIBLE_JOB_TEMPLATE_ID are set.
                                 
  -J, --job-template-id int      The Ansible Tower Job Template ID.
                                   Can also be set via the $ANSIBLE_JOB_TEMPLATE_ID environment variable.
                                    Only used if job template request 'template_id' is not set.
                                 
  -o, --output-log-file string   Write handler output to a log file.
                                   Can also be set via the $ANSIBLE_HANDLER_LOGFILE environment variable.
                                   Defaults to stdout if not set.
  -p, --port string              The Ansible Tower API port number.
                                   Can also be set via the $ANSIBLE_PORT environment variable.
                                  (default "443")
      --protocol string          The Ansible Tower API protocol (http or https).
                                   Can also be set via the $ANSIBLE_PROTO environment variable.
                                  (default "https")
  -S, --skip-validation          Skip validation of occurence and severity matching in requests; this is used primarily for testing.
                                   Cannot be combined with --strict
  -s, --strict                   Strictly require all requests to have severity and occurence matching defined.
                                   Cannot be combined with --skip-validation
  -t, --token string             The Ansible Tower API token.
                                   Can also be set via the $ANSIBLE_TOKEN environment variable.

Use "sensu-ansible-handler [command] --help" for more information about a command.

Example output

{"level":"info","msg":"INFO: No inventory host \"limit\" configured; defaulting to the Sensu Entity name: \"server-01\".\n","time":"2019-10-21T12:44:30-04:00"}
{"level":"info","msg":"INFO: requesting Job Template ID for the template named: \"Start Nginx\".\n","time":"2019-10-21T12:44:30-04:00"}
{"level":"info","msg":"INFO: 200 OK (https://127.0.0.1:443/api/v2/job_templates/).\n","time":"2019-10-21T12:44:31-04:00"}
{"level":"info","msg":"SUCCESS: found matching job template for \"Start Nginx\" with ID: \"7\".","time":"2019-10-21T12:44:31-04:00"}
{"level":"info","msg":"INFO: requesting Inventory ID for the inventory named: \"Sensu Go\".\n","time":"2019-10-21T12:44:31-04:00"}
{"level":"info","msg":"INFO: 200 OK (https://127.0.0.1:443/api/v2/inventories/).\n","time":"2019-10-21T12:44:31-04:00"}
{"level":"info","msg":"SUCCESS: found matching inventory \"Sensu Go\" with ID: \"2\".","time":"2019-10-21T12:44:31-04:00"}
{"level":"info","msg":"INFO: Launching the \"Start Nginx\" job template, targeting the \"server-01\" host (via the \"Sensu Go\" inventory).","time":"2019-10-21T12:44:31-04:00"}
{"level":"info","msg":"SUCCESS: 201 Created (https://127.0.0.1:443/api/v2/job_templates/7/launch/).\n","time":"2019-10-21T12:44:32-04:00"}

Configuration

Handler configuration

---
type: Handler
api_version: core/v2
metadata:
  name: ansible
  namespace: default
spec:
  type: pipe
  command: sensu-ansible-handler --host 127.0.0.1 --output-log-file /var/log/sensu/sensu-backend/sensu-ansible-handler.json.log
  timeout: 10
  env_vars:
  - "ANSIBLE_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Check configuration

---
type: CheckConfig
api_version: core/v2
metadata:
  name: check_nginx
  namespace: default
  annotations:
    # Required key: io.sensu.ansible.config.actions  
    #   Value: stringified json array of Job Template Requests
    #          all request attributes are optional
    # Each Job Template Request may consist of:
    #    Either template_name and/or template_id, with template_id taking precedence
    #    Either inventory_name and/or inventory_id, with inventory_id taking precedence
    #    Matching Sensu event occurrence conditions
    #    Matching Sensu event severity conditions
    #    Provide limit string to set inventory limit, empty string is replaced with entity name
    io.sensu.ansible.config.actions: |
      [
        {
          "template_name": "Start NGINX",
          "inventory_id": 2,
          "limit": "",
          "occurrences": [ 3 ],
          "severities": [ 1, 2 ]
        },
        {
          "template_id": 8,
          "inventory_name": "Web Servers",
          "limit": "",
          "occurrences": [ 10 ],
          "severities": [ 1, 2 ]
        }
      ]
spec:
  command: check_http -H 127.0.0.1
  publish: true
  interval: 10
  subscriptions:
  - nginx
  timeout: 10
  handlers:
  - ansible

Ansible configuration

Sensu will require a valid auth token to communicate with the Ansible Tower API.
Please note the following instructions on how to generate/obtain a valid Ansible
Tower authorization token.

1. Register Sensu as an Application in Ansible Tower.

   $ ANSIBLE_AUTH=$(curl -XPOST -sku ${ANSIBLE_USER}:${ANSIBLE_PASS} -H "Content-Type: application/json" \
     -d '{"organization": 1, "client_type": "confidential", "name": "Sensu Go", "authorization_grant_type": "implicit", "redirect_uris": "https://'${ANSIBLE_HOST}'/api/"}' \
     https://${ANSIBLE_HOST}/api/v2/applications/)
   

2. Get an OAuth Token.

   $ ANSIBLE_CLIENT_ID=$(echo $ANSIBLE_AUTH | jq -r .client_id)
   $ ANSIBLE_CLIENT_SECRET=$(echo $ANSIBLE_AUTH | jq -r .client_secret)
   $ open "http://${ANSIBLE_HOST}/api/o/authorize/?response_type=token&scope=read%20write&client_id=${ANSIBLE_CLIENT_ID}"
   

References

Documentation

• Ansible Tower API (reference documentation)
• Ansible Tower Token-Based Authentication (guide)

Development & Troubleshooting

• Get a list of organizations by ID:

  $ curl -XGET -sku ${ANSIBLE_USER}:${ANSIBLE_PASS} -H "Content-Type: application/json" \
    "https://${ANSIBLE_HOST}/api/v2/organizations/"
  

• Get a list of inventories:

  $ curl -XGET -sku ${ANSIBLE_USER}:${ANSIBLE_PASS} -H "Content-Type: application/json" \
    "https://${ANSIBLE_HOST}/api/v2/inventories/"
  

• Get a list of job_templates:

  $ curl -XGET -sku ${ANSIBLE_USER}:${ANSIBLE_PASS} -H "Content-Type: application/json" \
    "https://${ANSIBLE_HOST}/api/v2/job_templates/"
  

• Test an API Token:

  $ curl -XGET --insecure -I -H "Authorization: Bearer ${ANSIBLE_TOKEN}" \
    -H "Content-Type: application/json" \
    "https://${ANSIBLE_HOST}/api/v2/job_templates/"
  

• Create an inventory:

  $ curl -XPOST -H "Authorization: Bearer ${ANSIBLE_TOKEN}" -H "Content-Type: application/json" \
    -d '{"name": "Sensu Go", "organization": 1}' \
    "https://${ANSIBLE_HOST}/api/v2/inventories/"
  

• Create a host:

  $ curl -XPOST -H "Authorization: Bearer ${ANSIBLE_TOKEN}" -H "Content-Type: application/json" \
    -d '{"name": "server-01", "enabled": true, "instance_id": "", "variables": "{\"ansible_host\": \"10.0.1.101\"}"}' \
    "https://${ANSIBLE_HOST}/api/v2/inventories/2/hosts/"
  

• Launch a job template:

  $ curl -XPOST -H "Authorization: Bearer ${ANSIBLE_TOKEN}" -H "Content-Type: application/json" \
    -d '{"inventory": 2, "limit": "server-01"}' "https://${ANSIBLE_HOST}/api/v2/job_templates/7/launch/"
  

• Delete an application:

  $ curl -XDELETE -sku ${ANSIBLE_USER}:${ANSIBLE_PASS} -H "Content-Type: application/json" \
    "https://${ANSIBLE_HOST}/api/v2/applications/1/"
  

Roadmap

• TODO: look at Sensu => Ansible registration handler for maintaining
  "Smart Inventories"
• TODO: validate job template launch readiness via the GET /api/v2/job_templates/{id}/launch/ endpoint