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
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) |
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 |
“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
- name: indeni_step check if remote dns port is open indeni_step: task_description: "check if remote dns port is open" task_type: "DECISION" task_full_command: "nmap_output.stdout == 'open'" task_conclusion: "NO" task_full_output: "" when: nmap_output.stdout != 'open' |
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).
- name: dns server reachable block: - name: indeni_step check if dns server is pingable indeni_step: task_description: "check if dns server is pingable" task_type: "DECISION" task_full_command: "not ping_output.failed|bool" task_conclusion: "YES" task_full_output: "" - indeni_conclusion: triage_conclusion_title: dns server reachable triage_conclusion: > The dns server is reachable, but the dns port is not open. triage_has_conclusion: true triage_remediation_steps: > Please check if the configured dns server has dns service running. If the dns service operate properly, please check if some firewall is blocking the dns traffic. triage_has_remediation_steps: true - meta: end_play when: not ping_output.failed|bool |
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.
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),
- name: show running logging panos_op: ip_address: '{{ ip_address }}' username: '{{ username }}' password: '{{ password }}' cmd: 'show logging status' When: os.version == “1.0” - name: show running logging panos_op: ip_address: '{{ ip_address }}' username: '{{ username }}' password: '{{ password }}' cmd: 'show logging state When: os.version == “2.0” |