Skip to content

Commit

Permalink
doc: Fix wrong example commands (#893)
Browse files Browse the repository at this point in the history
  • Loading branch information
@gmuloc
gmuloc authored Oct 31, 2024
1 parent 898fdd3 commit 3649f54
Show file tree
Hide file tree
Showing 10 changed files with 217 additions and 153 deletions.
165 changes: 13 additions & 152 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/scripts/generate_svg.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
54 changes: 54 additions & 0 deletions docs/snippets/getting-started/anta_nrfu_json.output
View file
Original file line number Diff line number Diff line change
@@ -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
},
[...]
9 changes: 9 additions & 0 deletions docs/snippets/getting-started/anta_nrfu_json.sh
View file
Original file line number Diff line number Diff line change
@@ -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 <password> `\
--catalog ./catalog.yml \
json
Loading

0 comments on commit 3649f54

Please sign in to comment.