salt.returners.highstate_return module

Return the results of a highstate (or any other state function that returns data in a compatible format) via an HTML email or HTML file.

New in version 2017.7.0.

Similar results can be achieved by using smtp returner with a custom template, except an attempt at writing such a template for the complex data structure returned by highstate function had proven to be a challenge, not to mention that smtp module doesn't support sending HTML mail at the moment.

The main goal of this returner was producing an easy to read email similar to the output of highstate outputter used by the CLI.

This returner could be very useful during scheduled executions, but could also be useful for communicating the results of a manual execution.

Returner configuration is controlled in a standart fashion either via highstate group or an alternatively named group.

salt '*' state.highstate --return highstate

To use the alternative configuration, append '--return_config config-name'

salt '*' state.highstate --return highstate --return_config simple

Here is an example of what configuration might look like:

simple.highstate:
  report_failures: True
  report_changes: True
  report_everything: False
  failure_function: pillar.items
  success_function: pillar.items
  report_format: html
  report_delivery: smtp
  smtp_success_subject: 'success minion {id} on host {host}'
  smtp_failure_subject: 'failure minion {id} on host {host}'
  smtp_server: smtp.example.com
  smtp_recipients: saltusers@example.com, devops@example.com
  smtp_sender: salt@example.com

The report_failures, report_changes, and report_everything flags provide filtering of the results. If you want an email to be sent every time, then reprot_everything is your choice. If you want to be notified only when changes were successfully made use report_changes. And report_failures will generate an email if there were failures.

The configuration allows you to run salt module function in case of success (success_function) or failure (failure_function).

Any salt function, including ones defined in _module folder of your salt repo could be used here. Their output will be displayed under the 'extra' heading of the email.

Supported values for report_format are html, json, and yaml. The later two are typically used for debugging purposes, but could be used for applying a template at some later stage.

The values for report_delivery are smtp or file. In case of file delivery the only other applicable option is file_output.

In case of smtp delivery, smtp_* options demonstrated by the example above could be used to customize the email.

As you might have noticed success and failure subject contain {id} and {host} values. Any other grain name could be used. As opposed to using {{grains['id']}}, which will be rendered by the master and contain master's values at the time of pillar generation, these will contain minion values at the time of execution.

salt.returners.highstate_return.returner(ret)

Check highstate return information and possibly fire off an email or save a file.