diff --git a/README.md b/README.md index 0aa458e..364ae28 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ Name | Description ### Modules Name | Description --- | --- +[ansible.utils.cli_parse](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.cli_parse_module.rst)|Parse cli output or text using a variety of parsers [ansible.utils.fact_diff](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.fact_diff_module.rst)|Find the difference between currently set facts [ansible.utils.update_fact](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.update_fact_module.rst)|Update currently set facts [ansible.utils.validate](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.validate_module.rst)|Validate data with provided criteria diff --git a/changelogs/fragments/29-add_docs_for_Cli_parse.yaml b/changelogs/fragments/29-add_docs_for_Cli_parse.yaml new file mode 100644 index 0000000..867cf21 --- /dev/null +++ b/changelogs/fragments/29-add_docs_for_Cli_parse.yaml @@ -0,0 +1,3 @@ +--- +trivial: + - Add docs for cli_parse and fact_diff (https://github.com/ansible-collections/ansible.utils/pull/29) diff --git a/docs/ansible.utils.cli_parse_module.rst b/docs/ansible.utils.cli_parse_module.rst new file mode 100644 index 0000000..c33a9c1 --- /dev/null +++ b/docs/ansible.utils.cli_parse_module.rst @@ -0,0 +1,460 @@ +.. _ansible.utils.cli_parse_module: + + +*********************** +ansible.utils.cli_parse +*********************** + +**Parse cli output or text using a variety of parsers** + + +Version added: 1.0.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Parse cli output or text using a variety of parsers + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ command + +
+ string +
+ 		+ +
The command to run on the host
+
+
+ parser + +
+ dictionary + / required +
+ 		+ +
Parser specific parameters
+
+
+ command + +
+ string +
+ 		+ +
The command used to locate the parser's template
+
+
+ name + +
+ string + / required +
+ 		+ +
The name of the parser to use
+
+
+ os + +
+ string +
+ 		+ +
Provide an operating system value to the parser
+
For `ntc_templates` parser, this should be in the supported `<vendor>_<os>` format.
+
+
+ template_path + +
+ string +
+ 		+ +
Path of the parser template on the Ansible controller
+
This can be a relative or an absolute path
+
+
+ vars + +
+ dictionary +
+ 		+ +
Additional parser specific parameters
+
See the cli_parse user guide for examples of parser specific variables
+
https://docs.ansible.com/ansible/latest/network/user_guide/cli_parsing.html
+
+
+ set_fact + +
+ string +
+ 		+ +
Set the resulting parsed data as a fact
+
+
+ text + +
+ string +
+ 		+ +
Text to be parsed
+
+
+ + +Notes +----- + +.. note:: + - The default search path for a parser template is templates/{{ short_os }}_{{ command }}.{{ extension }} + - => short_os derived from ansible_network_os or ansible_distribution and set to lower case + - => command is the command passed to the module with spaces replaced with _ + - => extension is specific to the parser used (native=yaml, textfsm=textfsm, ttp=ttp) + - The default Ansible search path for the templates directory is used for parser templates as well + - Some parsers may have additional configuration options available. See the parsers/vars key and the parser's documentation + - Some parsers require third-party python libraries be installed on the Ansible control node and a specific python version + - e.g. Pyats requires pyats and genie and requires Python 3 + - e.g. ntc_templates requires ntc_templates + - e.g. textfsm requires textfsm + - e.g. ttp requires ttp + - e.g. xml requires xml_to_dict + - Support of 3rd party python libraries is limited to the use of their public APIs as documented + - Additional information and examples can be found in the parsing user guide: + - https://docs.ansible.com/ansible/latest/network/user_guide/cli_parsing.html + + + +Examples +-------- + +.. code-block:: yaml + + # Using the native parser + + # ------------- + # templates/nxos_show_interface.yaml + # - example: Ethernet1/1 is up + # getval: '(?P\S+) is (?P\S+)' + # result: + # "{{ name }}": + # name: "{{ name }}" + # state: + # operating: "{{ oper_state }}" + # shared: True + # + # - example: admin state is up, Dedicated Interface + # getval: 'admin state is (?P\S+)' + # result: + # "{{ name }}": + # name: "{{ name }}" + # state: + # admin: "{{ admin_state }}" + # + # - example: " Hardware: Ethernet, address: 0000.5E00.5301 (bia 0000.5E00.5301)" + # getval: '\s+Hardware: (?P.*), address: (?P\S+)' + # result: + # "{{ name }}": + # hardware: "{{ hardware }}" + # mac_address: "{{ mac }}" + + - name: Run command and parse with native + ansible.utils.cli_parse: + command: "show interface" + parser: + name: ansible.netcommon.native + set_fact: interfaces_fact + + + - name: Pass text and template_path + ansible.utils.cli_parse: + text: "{{ previous_command['stdout'] }}" + parser: + name: ansible.netcommon.native + template_path: "{{ role_path }}/templates/nxos_show_interface.yaml" + + + # Using the ntc_templates parser + + # ------------- + # The ntc_templates use 'vendor_platform' for the file name + # it will be derived from ansible_network_os if not provided + # e.g. cisco.ios.ios => cisco_ios + + - name: Run command and parse with ntc_templates + ansible.utils.cli_parse: + command: "show interface" + parser: + name: ansible.netcommon.ntc_templates + register: parser_output + + - name: Pass text and command + ansible.utils.cli_parse: + text: "{{ previous_command['stdout'] }}" + parser: + name: ansible.netcommon.ntc_templates + command: show interface + register: parser_output + + + # Using the pyats parser + + # ------------- + # The pyats parser uses 'os' to locate the appropriate parser + # it will be derived from ansible_network_os if not provided + # in the case of pyats: cisco.ios.ios => iosxe + + - name: Run command and parse with pyats + ansible.utils.cli_parse: + command: "show interface" + parser: + name: ansible.netcommon.pyats + register: parser_output + + - name: Pass text and command + ansible.utils.cli_parse: + text: "{{ previous_command['stdout'] }}" + parser: + name: ansible.netcommon.pyats + command: show interface + register: parser_output + + - name: Provide an OS to pyats to use an ios parser + ansible.utils.cli_parse: + text: "{{ previous_command['stdout'] }}" + parser: + name: ansible.netcommon.pyats + command: show interface + os: ios + register: parser_output + + + # Using the textfsm parser + + # ------------- + # templates/nxos_show_version.textfsm + # + # Value UPTIME ((\d+\s\w+.s.,?\s?){4}) + # Value LAST_REBOOT_REASON (.+) + # Value OS (\d+.\d+(.+)?) + # Value BOOT_IMAGE (.*) + # Value PLATFORM (\w+) + # + # Start + # ^\s+(NXOS: version|system:\s+version)\s+${OS}\s*$$ + # ^\s+(NXOS|kickstart)\s+image\s+file\s+is:\s+${BOOT_IMAGE}\s*$$ + # ^\s+cisco\s+${PLATFORM}\s+[cC]hassis + # ^\s+cisco\s+Nexus\d+\s+${PLATFORM} + # # Cisco N5K platform + # ^\s+cisco\s+Nexus\s+${PLATFORM}\s+[cC]hassis + # ^\s+cisco\s+.+-${PLATFORM}\s* + # ^Kernel\s+uptime\s+is\s+${UPTIME} + # ^\s+Reason:\s${LAST_REBOOT_REASON} -> Record + + - name: Run command and parse with textfsm + ansible.utils.cli_parse: + command: "show version" + parser: + name: ansible.utils.textfsm + register: parser_output + + - name: Pass text and command + ansible.utils.cli_parse: + text: "{{ previous_command['stdout'] }}" + parser: + name: ansible.utils.textfsm + command: show version + register: parser_output + + # Using the ttp parser + + # ------------- + # templates/nxos_show_interface.ttp + # + # {{ interface }} is {{ state }} + # admin state is {{ admin_state }}{{ ignore(".*") }} + + - name: Run command and parse with ttp + ansible.utils.cli_parse: + command: "show interface" + parser: + name: ansible.utils.ttp + set_fact: new_fact_key + + - name: Pass text and template_path + ansible.utils.cli_parse: + text: "{{ previous_command['stdout'] }}" + parser: + name: ansible.utils.ttp + template_path: "{{ role_path }}/templates/nxos_show_interface.ttp" + register: parser_output + + # Using the XML parser + + # ------------- + - name: Run command and parse with xml + ansible.utils.cli_parse: + command: "show interface | xml" + parser: + name: ansible.utils.xml + register: parser_output + + - name: Pass text and parse with xml + ansible.utils.cli_parse: + text: "{{ previous_command['stdout'] }}" + parser: + name: ansible.utils.xml + register: parser_output + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ parsed + +
+ dictionary +
+ 		always +
The structured data resulting from the parsing of the text
+
+
+
+ stdout + +
+ string +
+ 		when provided a command +
The output from the command run
+
+
+
+ stdout_lines + +
+ list +
+ 		when provided a command +
The output of the command run split into lines
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Bradley Thornton (@cidrblock) diff --git a/plugins/cli_parsers/json_parser.py b/plugins/cli_parsers/json_parser.py index c155021..adb16e5 100644 --- a/plugins/cli_parsers/json_parser.py +++ b/plugins/cli_parsers/json_parser.py @@ -7,6 +7,33 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type +DOCUMENTATION = """ + author: Bradley Thornton (@cidrblock) + name: json + short_description: Define configurable options for C(json) sub-plugin of C(cli_parse) module + description: + - This plugin documentation provides the configurable options that can be passed + to the I(ansible.utils.cli_parse) plugins when I(ansible.utils.json) is used as a value for + I(name) option. + version_added: 1.0.0 +""" + +EXAMPLES = r""" +- name: "Run command and parse with json" + ansible.utils.cli_parse: + command: "show version | json" + parser: + name: ansible.utils.json + register: nxos_json_command + +- name: "Load text and parse with json" + ansible.utils.cli_parse: + text: "{{ lookup('file', './nxos_show_interface_json_text.txt') }}" + parser: + name: ansible.utils.json + register: nxos_json_text +""" + import json from ansible.module_utils._text import to_native diff --git a/plugins/cli_parsers/textfsm_parser.py b/plugins/cli_parsers/textfsm_parser.py index c7c7c67..27a93c7 100644 --- a/plugins/cli_parsers/textfsm_parser.py +++ b/plugins/cli_parsers/textfsm_parser.py @@ -8,6 +8,34 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type +DOCUMENTATION = """ + author: Bradley Thornton (@cidrblock) + name: textfsm + short_description: Define configurable options for C(textfsm) sub-plugin of C(cli_parse) module + description: + - This plugin documentation provides the configurable options that can be passed + to the I(ansible.utils.cli_parse) plugins when I(ansible.utils.textfsm) is used as a value for + I(name) option. + version_added: 1.0.0 +""" + +EXAMPLES = r""" +- name: "Run command and parse with textfsm" + ansible.utils.cli_parse: + command: "show version" + parser: + name: ansible.utils.textfsm + register: nxos_textfsm_command + +- name: "Pass text and command" + ansible.utils.cli_parse: + text: "{{ lookup('file', '/home/user/files/nxos_show_version.txt') }}" + parser: + name: ansible.utils.textfsm + template_path: "/home/user/templates/nxos_show_version.textfsm" + register: nxos_textfsm_text +""" + import os from ansible.module_utils._text import to_native diff --git a/plugins/cli_parsers/ttp_parser.py b/plugins/cli_parsers/ttp_parser.py index 71ed6fe..6785c6a 100644 --- a/plugins/cli_parsers/ttp_parser.py +++ b/plugins/cli_parsers/ttp_parser.py @@ -8,6 +8,34 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type +DOCUMENTATION = """ + author: Bradley Thornton (@cidrblock) + name: ttp + short_description: Define configurable options for C(ttp) sub-plugin of C(cli_parse) module + description: + - This plugin documentation provides the configurable options that can be passed + to the I(ansible.utils.cli_parse) plugins when I(ansible.utils.ttp) is used as a value for + I(name) option. + version_added: 1.0.0 +""" + +EXAMPLES = r""" +- name: "Run command and parse with textfsm" + ansible.utils.cli_parse: + command: "show version" + parser: + name: ansible.utils.ttp + register: nxos_ttp_command + +- name: "Pass text and command" + ansible.utils.cli_parse: + text: "{{ lookup('file', '/home/user/files/nxos_show_version.txt') }}" + parser: + name: ansible.utils.textfsm + template_path: "/home/user/templates/nxos_show_version.ttp" + register: nxos_ttp_text +""" + import os from ansible.module_utils._text import to_native diff --git a/plugins/cli_parsers/xml_parser.py b/plugins/cli_parsers/xml_parser.py index e805d2d..fb8d320 100644 --- a/plugins/cli_parsers/xml_parser.py +++ b/plugins/cli_parsers/xml_parser.py @@ -8,6 +8,34 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type +DOCUMENTATION = """ + author: Bradley Thornton (@cidrblock) + name: xml + short_description: Define configurable options for C(xml) sub-plugin of C(cli_parse) module + description: + - This plugin documentation provides the configurable options that can be passed + to the I(ansible.utils.cli_parse) plugins when I(ansible.utils.xml) is used as a value for + I(name) option. + version_added: 1.0.0 +""" + +EXAMPLES = r""" +- name: "Run command and parse with xml" + ansible.utils.cli_parse: + command: "show interface | xml" + parser: + name: ansible.utils.xml + register: nxos_xml_command + +- name: "Pass text and parse with xml" + ansible.utils.cli_parse: + text: "{{ lookup('file', '/home/user/files/nxos_show_interface.xml') }}" + parser: + name: ansible.utils.xml + os: nxos + register: nxos_xml_text +""" + from ansible.module_utils._text import to_native from ansible.module_utils.basic import missing_required_lib from ansible_collections.ansible.utils.plugins.cli_parsers._base import ( diff --git a/plugins/fact_diff/native.py b/plugins/fact_diff/native.py index ea9c070..32bbe5e 100644 --- a/plugins/fact_diff/native.py +++ b/plugins/fact_diff/native.py @@ -7,6 +7,26 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type +DOCUMENTATION = """ + author: Bradley Thornton (@cidrblock) + name: native + short_description: Define configurable options for C(native) sub-plugin of C(fact_diff) module + description: + - This plugin documentation provides the configurable options that can be passed + to the I(ansible.utils.fact_diff) plugins when I(ansible.utils.native) is used as a value for + I(name) option of the module. + version_added: 1.0.0 +""" + +EXAMPLES = r""" +- name: Show the difference in json format + ansible.utils.fact_diff: + before: "{{ before }}" + after: "{{ after }}" + plugin: + name: ansible.utils.native +""" + import re from ansible.plugins.callback import CallbackBase from ansible_collections.ansible.utils.plugins.module_utils.base_classes.fact_diff import ( diff --git a/plugins/filter/get_path.py b/plugins/filter/get_path.py index d648089..7796cd6 100644 --- a/plugins/filter/get_path.py +++ b/plugins/filter/get_path.py @@ -12,7 +12,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = """ - filter: get_path + name: get_path author: Bradley Thornton (@cidrblock) version_added: "1.0.0" short_description: Retrieve the value in a variable using a path diff --git a/plugins/filter/index_of.py b/plugins/filter/index_of.py index b5d4c5a..d46298e 100644 --- a/plugins/filter/index_of.py +++ b/plugins/filter/index_of.py @@ -12,7 +12,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = """ - filter: index_of + name: index_of author: Bradley Thornton (@cidrblock) version_added: "1.0.0" short_description: Find the indices of items in a list matching some criteria diff --git a/plugins/filter/to_paths.py b/plugins/filter/to_paths.py index 7829b48..14d59c3 100644 --- a/plugins/filter/to_paths.py +++ b/plugins/filter/to_paths.py @@ -13,7 +13,7 @@ __metaclass__ = type DOCUMENTATION = """ - filter: to_paths + name: to_paths author: Bradley Thornton (@cidrblock) version_added: "1.0.0" short_description: Flatten a complex object into a dictionary of paths and values diff --git a/plugins/filter/validate.py b/plugins/filter/validate.py index e919cf5..fa0c443 100644 --- a/plugins/filter/validate.py +++ b/plugins/filter/validate.py @@ -3,7 +3,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = """ - filter: validate + name: validate author: Ganesh Nalawade (@ganeshrn) version_added: "1.0.0" short_description: Validate data with provided criteria diff --git a/plugins/lookup/get_path.py b/plugins/lookup/get_path.py index 0536df9..bd32d77 100644 --- a/plugins/lookup/get_path.py +++ b/plugins/lookup/get_path.py @@ -13,7 +13,7 @@ __metaclass__ = type DOCUMENTATION = """ - lookup: get_path + name: get_path author: Bradley Thornton (@cidrblock) version_added: "1.0.0" short_description: Retrieve the value in a variable using a path diff --git a/plugins/lookup/index_of.py b/plugins/lookup/index_of.py index a344f50..8ac34b3 100644 --- a/plugins/lookup/index_of.py +++ b/plugins/lookup/index_of.py @@ -13,7 +13,7 @@ __metaclass__ = type DOCUMENTATION = """ - lookup: index_of + name: index_of author: Bradley Thornton (@cidrblock) version_added: "1.0.0" short_description: Find the indices of items in a list matching some criteria diff --git a/plugins/lookup/to_paths.py b/plugins/lookup/to_paths.py index 33dbcd7..a8c66d2 100644 --- a/plugins/lookup/to_paths.py +++ b/plugins/lookup/to_paths.py @@ -13,7 +13,7 @@ __metaclass__ = type DOCUMENTATION = """ - lookup: to_paths + name: to_paths author: Bradley Thornton (@cidrblock) version_added: "1.0.0" short_description: Flatten a complex object into a dictionary of paths and values diff --git a/plugins/lookup/validate.py b/plugins/lookup/validate.py index 1347553..80c66f2 100644 --- a/plugins/lookup/validate.py +++ b/plugins/lookup/validate.py @@ -8,7 +8,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = """ - lookup: validate + name: validate author: Ganesh Nalawade (@ganeshrn) version_added: "1.0.0" short_description: Validate data with provided criteria diff --git a/plugins/test/validate.py b/plugins/test/validate.py index 8ff73af..5e4c210 100644 --- a/plugins/test/validate.py +++ b/plugins/test/validate.py @@ -7,7 +7,7 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = """ - test: validate + name: validate author: Ganesh Nalawade (@ganeshrn) version_added: "1.0.0" short_description: Validate data with provided criteria diff --git a/plugins/validate/jsonschema.py b/plugins/validate/jsonschema.py index cd36485..e1b24eb 100644 --- a/plugins/validate/jsonschema.py +++ b/plugins/validate/jsonschema.py @@ -9,7 +9,7 @@ __metaclass__ = type DOCUMENTATION = """ author: Ganesh Nalawade (@ganeshrn) - validate: jsonschema + name: jsonschema short_description: Define configurable options for jsonschema validate plugin description: - This plugin documentation provides the configurable options that can be passed