diff --git a/docs/getting-started.md b/docs/getting-started.md index aac88c640..bcd5a2c51 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -48,26 +48,7 @@ management api http-commands ANTA uses an inventory to list the target devices for the tests. You can create a file manually with this format: ```yaml -anta_inventory: - hosts: - - host: 192.168.0.10 - name: spine01 - tags: ['fabric', 'spine'] - - host: 192.168.0.11 - name: spine02 - tags: ['fabric', 'spine'] - - host: 192.168.0.12 - name: leaf01 - tags: ['fabric', 'leaf'] - - host: 192.168.0.13 - name: leaf02 - tags: ['fabric', 'leaf'] - - host: 192.168.0.14 - name: leaf03 - tags: ['fabric', 'leaf'] - - host: 192.168.0.15 - name: leaf04 - tags: ['fabric', 'leaf'] +--8<-- "getting-started/inventory.yml" ``` > You can read more details about how to build your inventory [here](usage-inventory-catalog.md#device-inventory) @@ -90,31 +71,7 @@ The structure to follow is like: Here is an example for basic tests: ```yaml -# Load anta.tests.software -anta.tests.software: - - VerifyEOSVersion: # Verifies the device is running one of the allowed EOS version. - versions: # List of allowed EOS versions. - - 4.25.4M - - 4.26.1F - - '4.28.3M-28837868.4283M (engineering build)' - - VerifyTerminAttrVersion: - versions: - - v1.22.1 - -anta.tests.system: - - VerifyUptime: # Verifies the device uptime is higher than a value. - minimum: 1 - - VerifyNTP: - - VerifySyslog: - -anta.tests.mlag: - - VerifyMlagStatus: - - VerifyMlagInterfaces: - - VerifyMlagConfigSanity: - -anta.tests.configuration: - - VerifyZeroTouch: # Verifies ZeroTouch is disabled. - - VerifyRunningConfigDiffs: +--8<-- "getting-started/catalog.yml" ``` ## Test your network @@ -135,128 +92,32 @@ This entrypoint has multiple options to manage test coverage and reporting. To run the NRFU, you need to select an output format amongst ["json", "table", "text", "tpl-report"]. For a first usage, `table` is recommended. By default all test results for all devices are rendered but it can be changed to a report per test case or per host +!!! Note + The following examples shows how to pass all the CLI options. + + See how to use environment variables instead in the [CLI overview](cli/overview.md#anta-environment-variables) + #### Default report using table ```bash -anta nrfu \ - --username tom \ - --password arista123 \ - --enable \ - --enable-password t \ - --inventory .personal/inventory_atd.yml \ - --catalog .personal/tests-bases.yml \ - table --tags leaf - - -╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ -╰──────────────────────────────────────────────────────╯ -[10:17:24] INFO Running ANTA tests... runner.py:75 - • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40/40 • 0:00:02 • 0:00:00 - - All tests results -┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ -┃ Device IP ┃ Test Name ┃ Test Status ┃ Message(s) ┃ Test description ┃ Test category ┃ -┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ -│ leaf01 │ VerifyEOSVersion │ success │ │ Verifies the device is running one of the allowed EOS version. │ software │ -│ leaf01 │ VerifyTerminAttrVersion │ success │ │ Verifies the device is running one of the allowed TerminAttr │ software │ -│ │ │ │ │ version. │ │ -│ leaf01 │ VerifyUptime │ success │ │ Verifies the device uptime is higher than a value. │ system │ -│ leaf01 │ VerifyNTP │ success │ │ Verifies NTP is synchronised. │ system │ -│ leaf01 │ VerifySyslog │ success │ │ Verifies the device had no syslog message with a severity of warning │ system │ -│ │ │ │ │ (or a more severe message) during the last 7 days. │ │ -│ leaf01 │ VerifyMlagStatus │ skipped │ MLAG is disabled │ This test verifies the health status of the MLAG configuration. │ mlag │ -│ leaf01 │ VerifyMlagInterfaces │ skipped │ MLAG is disabled │ This test verifies there are no inactive or active-partial MLAG │ mlag │ -[...] -│ leaf04 │ VerifyMlagConfigSanity │ skipped │ MLAG is disabled │ This test verifies there are no MLAG config-sanity inconsistencies. │ mlag │ -│ leaf04 │ VerifyZeroTouch │ success │ │ Verifies ZeroTouch is disabled. │ configuration │ -│ leaf04 │ VerifyRunningConfigDiffs │ success │ │ │ configuration │ -└───────────┴──────────────────────────┴─────────────┴──────────────────┴──────────────────────────────────────────────────────────────────────┴───────────────┘ +--8<-- "getting-started/anta_nrfu_table.sh" +--8<-- "getting-started/anta_nrfu_table.output" ``` #### Report in text mode ```bash -$ anta nrfu \ - --username tom \ - --password arista123 \ - --enable \ - --enable-password t \ - --inventory .personal/inventory_atd.yml \ - --catalog .personal/tests-bases.yml \ - text --tags leaf - -╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ -╰──────────────────────────────────────────────────────╯ -[10:20:47] INFO Running ANTA tests... runner.py:75 - • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40/40 • 0:00:01 • 0:00:00 -leaf01 :: VerifyEOSVersion :: SUCCESS -leaf01 :: VerifyTerminAttrVersion :: SUCCESS -leaf01 :: VerifyUptime :: SUCCESS -leaf01 :: VerifyNTP :: SUCCESS -leaf01 :: VerifySyslog :: SUCCESS -leaf01 :: VerifyMlagStatus :: SKIPPED (MLAG is disabled) -leaf01 :: VerifyMlagInterfaces :: SKIPPED (MLAG is disabled) -leaf01 :: VerifyMlagConfigSanity :: SKIPPED (MLAG is disabled) -[...] +--8<-- "getting-started/anta_nrfu_text.sh" +--8<-- "getting-started/anta_nrfu_text.output" ``` #### Report in JSON format ```bash -$ anta nrfu \ - --username tom \ - --password arista123 \ - --enable \ - --enable-password t \ - --inventory .personal/inventory_atd.yml \ - --catalog .personal/tests-bases.yml \ - json --tags leaf - -╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ -╰──────────────────────────────────────────────────────╯ -[10:21:51] INFO Running ANTA tests... runner.py:75 - • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40/40 • 0:00:02 • 0:00:00 -╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ -│ JSON results of all tests │ -╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ -[ - { - "name": "leaf01", - "test": "VerifyEOSVersion", - "categories": [ - "software" - ], - "description": "Verifies the device is running one of the allowed EOS version.", - "result": "success", - "messages": [], - "custom_field": "None", - }, - { - "name": "leaf01", - "test": "VerifyTerminAttrVersion", - "categories": [ - "software" - ], - "description": "Verifies the device is running one of the allowed TerminAttr version.", - "result": "success", - "messages": [], - "custom_field": "None", - }, -[...] -] +--8<-- "getting-started/anta_nrfu_json.sh" +--8<-- "getting-started/anta_nrfu_json.output" ``` -You can find more information under the **usage** section of the website - ### Basic usage in a Python script ```python diff --git a/docs/scripts/generate_svg.py b/docs/scripts/generate_svg.py index f017b243d..2eca6ac4a 100644 --- a/docs/scripts/generate_svg.py +++ b/docs/scripts/generate_svg.py @@ -94,7 +94,7 @@ def custom_progress_bar() -> Progress: # Redirect stdout of the program towards another StringIO to capture help # that is not part or anta rich console # redirect potential progress bar output to console by patching - with patch("anta.cli.nrfu.anta_progress_bar", custom_progress_bar), suppress(SystemExit): + with patch("anta.cli.nrfu.utils.anta_progress_bar", custom_progress_bar), suppress(SystemExit): function() if "--help" in args: diff --git a/docs/snippets/getting-started/anta_nrfu_json.output b/docs/snippets/getting-started/anta_nrfu_json.output new file mode 100644 index 000000000..c6db49d43 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_json.output @@ -0,0 +1,54 @@ +╭────────────────────── Settings ──────────────────────╮ +│ - ANTA Inventory contains 5 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 9 tests │ +╰──────────────────────────────────────────────────────╯ + +[10:53:11] INFO Preparing ANTA NRFU Run ... tools.py:294 + INFO Connecting to devices ... tools.py:294 + INFO Connecting to devices completed in: 0:00:00.053. tools.py:302 + INFO Preparing the tests ... tools.py:294 + INFO Preparing the tests completed in: 0:00:00.001. tools.py:302 + INFO --- ANTA NRFU Run Information --- runner.py:276 + Number of devices: 5 (5 established) + Total number of selected tests: 45 + Maximum number of open file descriptors for the current ANTA process: 16384 + --------------------------------- + INFO Preparing ANTA NRFU Run completed in: 0:00:00.065. tools.py:302 + INFO Running ANTA tests ... tools.py:294 +[10:53:12] INFO Running ANTA tests completed in: 0:00:00.857. tools.py:302 + INFO Cache statistics for 's1-spine1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-spine2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf3': 1 hits / 9 command(s) (11.11%) runner.py:75 + • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45/45 • 0:00:00 • 0:00:00 + +╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ +│ JSON results │ +╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ +[ + { + "name": "s1-spine1", + "test": "VerifyNTP", + "categories": [ + "system" + ], + "description": "Verifies if NTP is synchronised.", + "result": "success", + "messages": [], + "custom_field": null + }, + { + "name": "s1-spine1", + "test": "VerifyMlagConfigSanity", + "categories": [ + "mlag" + ], + "description": "Verifies there are no MLAG config-sanity inconsistencies.", + "result": "skipped", + "messages": [ + "MLAG is disabled" + ], + "custom_field": null + }, + [...] diff --git a/docs/snippets/getting-started/anta_nrfu_json.sh b/docs/snippets/getting-started/anta_nrfu_json.sh new file mode 100644 index 000000000..932aeb33c --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_json.sh @@ -0,0 +1,9 @@ +anta nrfu \ + --username arista \ + --password arista \ + --inventory ./inventory.yml \ + `# uncomment the next two lines if you have an enable password `\ + `# --enable `\ + `# --enable-password `\ + --catalog ./catalog.yml \ + json diff --git a/docs/snippets/getting-started/anta_nrfu_table.output b/docs/snippets/getting-started/anta_nrfu_table.output new file mode 100644 index 000000000..a34b5bd99 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_table.output @@ -0,0 +1,47 @@ +╭────────────────────── Settings ──────────────────────╮ +│ - ANTA Inventory contains 5 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 9 tests │ +╰──────────────────────────────────────────────────────╯ + +[10:53:01] INFO Preparing ANTA NRFU Run ... tools.py:294 + INFO Connecting to devices ... tools.py:294 + INFO Connecting to devices completed in: 0:00:00.058. tools.py:302 + INFO Preparing the tests ... tools.py:294 + INFO Preparing the tests completed in: 0:00:00.001. tools.py:302 + INFO --- ANTA NRFU Run Information --- runner.py:276 + Number of devices: 5 (5 established) + Total number of selected tests: 45 + Maximum number of open file descriptors for the current ANTA process: 16384 + --------------------------------- + INFO Preparing ANTA NRFU Run completed in: 0:00:00.069. tools.py:302 + INFO Running ANTA tests ... tools.py:294 +[10:53:02] INFO Running ANTA tests completed in: 0:00:00.969. tools.py:302 + INFO Cache statistics for 's1-spine1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-spine2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf3': 1 hits / 9 command(s) (11.11%) runner.py:75 + • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45/45 • 0:00:00 • 0:00:00 + + All tests results +┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ +┃ Device ┃ Test Name ┃ Test Status ┃ Message(s) ┃ Test description ┃ Test category ┃ +┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ +│ s1-spine1 │ VerifyMlagConfigSanity │ skipped │ MLAG is disabled │ Verifies there are no MLAG config-sanity │ MLAG │ +│ │ │ │ │ inconsistencies. │ │ +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +│ s1-spine1 │ VerifyEOSVersion │ failure │ device is running version │ Verifies the EOS version of the device. │ Software │ +│ │ │ │ "4.32.2F-38195967.4322F (engineering │ │ │ +│ │ │ │ build)" not in expected versions: │ │ │ +│ │ │ │ ['4.25.4M', '4.26.1F', │ │ │ +│ │ │ │ '4.28.3M-28837868.4283M (engineering │ │ │ +│ │ │ │ build)'] │ │ │ +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +[...] +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +│ s1-leaf3 │ VerifyTerminAttrVersion │ failure │ device is running TerminAttr version │ Verifies the TerminAttr version of the │ Software │ +│ │ │ │ v1.34.0 and is not in the allowed list: │ device. │ │ +│ │ │ │ ['v1.22.1'] │ │ │ +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +│ s1-leaf3 │ VerifyZeroTouch │ success │ │ Verifies ZeroTouch is disabled │ Configuration │ +└───────────┴──────────────────────────┴─────────────┴────────────────────────────────────────────┴────────────────────────────────────────────┴───────────────┘ diff --git a/docs/snippets/getting-started/anta_nrfu_table.sh b/docs/snippets/getting-started/anta_nrfu_table.sh new file mode 100644 index 000000000..785c41854 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_table.sh @@ -0,0 +1,10 @@ +anta nrfu \ + --username arista \ + --password arista \ + --inventory ./inventory.yml \ + `# uncomment the next two lines if you have an enable password `\ + `# --enable` \ + `# --enable-password ` \ + --catalog ./catalog.yml \ + `# table is default if not provided` \ + table diff --git a/docs/snippets/getting-started/anta_nrfu_text.output b/docs/snippets/getting-started/anta_nrfu_text.output new file mode 100644 index 000000000..872f60810 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_text.output @@ -0,0 +1,30 @@ +╭────────────────────── Settings ──────────────────────╮ +│ - ANTA Inventory contains 5 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 9 tests │ +╰──────────────────────────────────────────────────────╯ + +[10:52:39] INFO Preparing ANTA NRFU Run ... tools.py:294 + INFO Connecting to devices ... tools.py:294 + INFO Connecting to devices completed in: 0:00:00.057. tools.py:302 + INFO Preparing the tests ... tools.py:294 + INFO Preparing the tests completed in: 0:00:00.001. tools.py:302 + INFO --- ANTA NRFU Run Information --- runner.py:276 + Number of devices: 5 (5 established) + Total number of selected tests: 45 + Maximum number of open file descriptors for the current ANTA process: 16384 + --------------------------------- + INFO Preparing ANTA NRFU Run completed in: 0:00:00.068. tools.py:302 + INFO Running ANTA tests ... tools.py:294 +[10:52:40] INFO Running ANTA tests completed in: 0:00:00.863. tools.py:302 + INFO Cache statistics for 's1-spine1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-spine2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf3': 1 hits / 9 command(s) (11.11%) runner.py:75 + • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45/45 • 0:00:00 • 0:00:00 + +s1-spine1 :: VerifyEOSVersion :: FAILURE(device is running version "4.32.2F-38195967.4322F (engineering build)" not in expected versions: ['4.25.4M', '4.26.1F', +'4.28.3M-28837868.4283M (engineering build)']) +s1-spine1 :: VerifyTerminAttrVersion :: FAILURE(device is running TerminAttr version v1.34.0 and is not in the allowed list: ['v1.22.1']) +s1-spine1 :: VerifyZeroTouch :: SUCCESS() +s1-spine1 :: VerifyMlagConfigSanity :: SKIPPED(MLAG is disabled) diff --git a/docs/snippets/getting-started/anta_nrfu_text.sh b/docs/snippets/getting-started/anta_nrfu_text.sh new file mode 100644 index 000000000..3835b51c8 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_text.sh @@ -0,0 +1,9 @@ +anta nrfu \ + --username arista \ + --password arista \ + --inventory ./inventory.yml \ + `# uncomment the next two lines if you have an enable password `\ + `# --enable` \ + `# --enable-password ` \ + --catalog ./catalog.yml \ + text diff --git a/docs/snippets/getting-started/catalog.yml b/docs/snippets/getting-started/catalog.yml new file mode 100644 index 000000000..cc7e7810a --- /dev/null +++ b/docs/snippets/getting-started/catalog.yml @@ -0,0 +1,24 @@ +--- +anta.tests.software: + - VerifyEOSVersion: # Verifies the device is running one of the allowed EOS version. + versions: # List of allowed EOS versions. + - 4.25.4M + - 4.26.1F + - '4.28.3M-28837868.4283M (engineering build)' + - VerifyTerminAttrVersion: + versions: + - v1.22.1 + +anta.tests.system: + - VerifyUptime: # Verifies the device uptime is higher than a value. + minimum: 1 + - VerifyNTP: + +anta.tests.mlag: + - VerifyMlagStatus: + - VerifyMlagInterfaces: + - VerifyMlagConfigSanity: + +anta.tests.configuration: + - VerifyZeroTouch: # Verifies ZeroTouch is disabled. + - VerifyRunningConfigDiffs: diff --git a/docs/snippets/getting-started/inventory.yml b/docs/snippets/getting-started/inventory.yml new file mode 100644 index 000000000..2f3d5127a --- /dev/null +++ b/docs/snippets/getting-started/inventory.yml @@ -0,0 +1,20 @@ +anta_inventory: + hosts: + - host: 192.168.0.10 + name: s1-spine1 + tags: ['fabric', 'spine'] + - host: 192.168.0.11 + name: s1-spine2 + tags: ['fabric', 'spine'] + - host: 192.168.0.12 + name: s1-leaf1 + tags: ['fabric', 'leaf'] + - host: 192.168.0.13 + name: s1-leaf2 + tags: ['fabric', 'leaf'] + - host: 192.168.0.14 + name: s1-leaf3 + tags: ['fabric', 'leaf'] + - host: 192.168.0.15 + name: s1-leaf3 + tags: ['fabric', 'leaf']