Guidelines for playbook: Output macros
Task output
Every playbook contains a lot of tasks.
Some of the tasks are important and should be viewed in the UI.
Some of the tasks are minor and irrelevant for the user.
In order to distinguish between the tasks, the IKE should use the indeni_task module to export a task that should be viewed in the UI.
There are 2 types of tasks in the UI:
Action - describes a command exception
Decision - describes a question and the result
indeni_task module
The structure to pass to indeni_task is:
indeni_task:
task_description: type string
task_type: type string
task_full_command: type string
task_conclusion: type string (for Decision should be YES/NO)
task_full_output: type string (for Decision should be empty)
indeni_conclusion
The whole purpose of the automation integration is to give the user some kind of conclusion and remediation steps.
The question is, “How can we know from the playbook results what is the conclusion?”
In order to deal with remediation steps, indeni_conclusion module can be used.
indeni_conclusion can be used as the final task for every possible flow.
The structure to pass to indeni_conclusion is:
indeni_conclusion:
Triage_conclusion_title: type string
Triage_has_conclusion: type boolean
Triage_conclusion: type string
Triage_has_remediation_steps: type boolean
Triage_remediation_steps: type string
Examples
“ACTION” step is used - to describe a command execution
- name: get dns server address
panos_set:
ip_address: '{{ip_address}}'
username: '{{username}}'
password: '{{password}}'
xpath: '/config/devices/entry/deviceconfig/system/dns-setting/servers'
command: 'show'
register: dns_server_result
ignore_errors: yes
- name: indeni_step get dns server address
indeni_step:
task_description: "get dns server address"
task_type: "ACTION"
task_full_command: "config xpath /config/devices/entry/deviceconfig/system/dns-setting/servers"
task_conclusion: "xml response received, need further parse"
task_full_output: "{{dns_server_result}}"Right before the “ACTION” description is the actual command execution. indeni_step execution will provide the data that will be displayed in UI if a user choose to see the execution details.
2. “DECISION” is used - to describe a test result
Here we have just ran a test to check whether the remote port is open and we would like to display this test result in the UI.
The indeni_step is meant to be used in each important command execution and decision.
3. Indeni_conclusion is used to describe what conclusion the script has reached before the script terminates. For each exit point, there shall be a conclusion, even if a root cause can’t be found (no explicit root cause is also some sort of conclusion).
Here, the test result of ping_output.failed is used to derive a “DECISION”, it also branch out an exit point (meta: end_play) therefore a conclusion has to be made here.
Device Tags
A playbook has dependency on devices' vendor/product/model/version.
For example, for Palo Alto, a firewall device has different command sets than Panorama. This means, a playbook designed for firewall may not work for Panorama and vice versa.
The collector has already acquired the information about device vendor/product/model/version as device tags. To avoid playbook re-collect those info from the device, the server should pass device tags to the playbook.
The following tags shall be used at the top of the playbook: os.name, product, model. A playbook should exit with a conclusion at the beginning if these tags do not meet the requirements.
Some device commands may have version difference (command or output format).
Such differences should be handled for the applicable command execution and parsing based on the version. For example (hypothetically),