salt.returners.highstate_return¶

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.

Similar results can be achieved by using the 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 the smtp module doesn't support sending HTML mail at the moment.

The main goal of this returner was to produce 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 standard 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 the 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_port: 25
  smtp_tls: False
  smtp_username: username
  smtp_password: password
  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 report_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 a salt module function in case of success (success_function) or failure (failure_function).

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

Supported values for report_format are html, json, and yaml. The latter 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, the success and failure subjects 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.