doc: update outdated doc

aristanetworks · Sep 17, 2024 · 427f72e · 427f72e
1 parent abff55a
commit 427f72e
Show file tree

Hide file tree

Showing 2 changed files with 174 additions and 133 deletions.
diff --git a/docs/advanced_usages/as-python-lib.md b/docs/advanced_usages/as-python-lib.md
@@ -40,8 +40,11 @@ The [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) class is a
 - The [connect_inventory()](../api/inventory.md#anta.inventory.AntaInventory.connect_inventory) coroutine will execute the [refresh()](../api/device.md#anta.device.AntaDevice.refresh) coroutines of all the devices in the inventory.
 - The [parse()](../api/inventory.md#anta.inventory.AntaInventory.parse) static method creates an [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) instance from a YAML file and returns it. The devices are [AsyncEOSDevice](../api/device.md#anta.device.AsyncEOSDevice) instances.
 
+## Examples
 
-To parse a YAML inventory file and print the devices connection status:
+##### Parse an ANTA inventory file
+
+> This script parses an ANTA inventory file, connects to devices and print their status
 
 ```python
 """
@@ -81,7 +84,10 @@ if __name__ == "__main__":
 ??? note "How to create your inventory file"
     Please visit this [dedicated section](../usage-inventory-catalog.md) for how to use inventory and catalog files.
 
-To run an EOS commands list on the reachable devices from the inventory:
+##### Run EOS commands
+
+> This script runs a list of EOS commands on reachable devices
+
 ```python
 """
 Example

diff --git a/docs/cli/tag-management.md b/docs/cli/tag-management.md
@@ -3,163 +3,198 @@
   ~ Use of this source code is governed by the Apache License 2.0
   ~ that can be found in the LICENSE file.
   -->
+## Overview
 
-# Tag management
+ANTA commands can be used with a `--tags` option. This option **filters the inventory** with the specified tag(s) when running the command.
 
-## Overview
+Tags can also be used to **restrict a specific test** to a set of devices when using `anta nrfu`.
+
+## Defining tags
+
+### Device tags
+
+Device tags can be defined in the inventory:
+
+```yaml
+anta_inventory:
+  hosts:
+    - name: leaf1
+      host: leaf1.anta.arista.com
+      tags: ["leaf"]
+    - name: leaf2
+      host: leaf2.anta.arista.com
+      tags: ["leaf"]
+    - name: spine1
+      host: spine1.anta.arista.com
+      tags: ["spine"]
+```
+
+Each device also has its own name automatically added as a tag:
+
+```bash
+anta get inventory
+Current inventory content is:
+{
+    'leaf1': AsyncEOSDevice(
+        name='leaf1',
+        tags={'leaf', 'leaf1'},  <--
+        [...]
+        host='leaf1.anta.arista.com',
+        [...]
+    ),
+    'leaf2': AsyncEOSDevice(
+        name='leaf2',
+        tags={'leaf', 'leaf2'},  <--
+        [...]
+        host='leaf2.anta.arista.com',
+        [...]
+    ),
+    'spine1': AsyncEOSDevice(
+        name='spine1',
+        tags={'spine1', 'spine'},  <--
+        [...]
+        host='spine1.anta.arista.com',
+        [...]
+    )
+}
+```
 
-Some of the ANTA commands like `anta nrfu` command come with a `--tags` option.
+### Test tags
+
+Tags can be defined in the test catalog to restrict tests to tagged devices:
+
+```yaml
+anta.tests.system:
+  - VerifyUptime:
+      minimum: 10
+      filters:
+        tags: ['spine']
+  - VerifyUptime:
+      minimum: 9
+      filters:
+        tags: ['leaf']
+  - VerifyReloadCause:
+      filters:
+        tags: ['spine', 'leaf']
+  - VerifyCoredump:
+  - VerifyAgentLogs:
+  - VerifyCPUUtilization:
+  - VerifyMemoryUtilization:
+  - VerifyFileSystemUtilization:
+  - VerifyNTP:
+
+anta.tests.mlag:
+  - VerifyMlagStatus:
+      filters:
+        tags: ['leaf']
+
+anta.tests.interfaces:
+  - VerifyL3MTU:
+      mtu: 1500
+      filters:
+        tags: ['spine']
+```
 
-For `nrfu`, this allows users to specify a set of tests, marked with a given tag, to be run on devices marked with the same tag. For instance, you can run tests dedicated to leaf devices on your leaf devices only and not on other devices.
+> A tag used to filter a test can also be a device name
 
-Tags are string defined by the user and can be anything considered as a string by Python. A [default one](#default-tags) is present for all tests and devices.
+!!! tip "Use different input values for a specific test"
+    Leverage tags to define different input values for a specific test. See the `VerifyUptime` example above.
 
-The next table provides a short summary of the scope of tags using CLI
+## Using tags
 
 | Command | Description |
 | ------- | ----------- |
-| `none` | Run all tests on all devices according `tag` definition in your inventory and test catalog. And tests with no tag are executed on all devices|
-| `--tags leaf` | Run all tests marked with `leaf` tag on all devices configured with `leaf` tag.<br/> All other tags are ignored |
-| `--tags leaf,spine` | Run all tests marked with `leaf` tag on all devices configured with `leaf` tag.<br/>Run all tests marked with `spine` tag on all devices configured with `spine` tag.<br/> All other tags are ignored |
-
-## Inventory and Catalog for tests
-
-All commands in this page are based on the following inventory and test catalog.
-
-=== "Inventory"
-
-    ```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'
-    ```
-
-=== "Test Catalog"
-
-    ```yaml
-    anta.tests.system:
-      - VerifyUptime:
-          minimum: 10
-          filters:
-            tags: ['fabric']
-      - VerifyReloadCause:
-          tags: ['leaf', spine']
-      - VerifyCoredump:
-      - VerifyAgentLogs:
-      - VerifyCPUUtilization:
-          filters:
-            tags: ['spine', 'leaf']
-      - VerifyMemoryUtilization:
-      - VerifyFileSystemUtilization:
-      - VerifyNTP:
-
-    anta.tests.mlag:
-      - VerifyMlagStatus:
-
-
-    anta.tests.interfaces:
-      - VerifyL3MTU:
-          mtu: 1500
-          filters:
-            tags: ['demo']
-    ```
-
-## Default tags
-
-By default, ANTA uses a default tag for both devices and tests. This default tag is `all` and it can be explicit if you want to make it visible in your inventory and also implicit since the framework injects this tag if it is not defined.
-
-So this command will run all tests from your catalog on all devices. With a mapping for `tags` defined in your inventory and catalog. If no `tags` configured, then tests are executed against all devices.
+| No `--tags` option | Run all tests on all devices according `tag` definition in your inventory and test catalog.<br/> Tests without tag are executed on all devices. |
+| `--tags leaf` | Run all tests marked with `leaf` tag on all devices configured with `leaf` tag.<br/> All other tests are ignored. |
+| `--tags leaf,spine` | Run all tests marked with `leaf` tag on all devices configured with `leaf` tag.<br/>Run all tests marked with `spine` tag on all devices configured with `spine` tag.<br/> All other tests are ignored. |
 
-```bash
-$ anta nrfu -c .personal/catalog-class.yml table --group-by device
+### Examples
+
+The following examples use the inventory and test catalog defined above.
 
+##### No `--tags` option
+
+Tests without tag are run on all devices.
+Tests with tags will only run on devices with matching tags.
+
+```bash
+$ anta nrfu table --group-by device
 ╭────────────────────── Settings ──────────────────────╮
-│ Running ANTA tests:                                  │
-│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │
-│ - Tests catalog contains 10 tests                    │
+│ - ANTA Inventory contains 3 devices (AsyncEOSDevice) │
+│ - Tests catalog contains 11 tests                    │
 ╰──────────────────────────────────────────────────────╯
 
-┏━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ Device  ┃ # of success ┃ # of skipped ┃ # of failure ┃ # of errors ┃ List of failed or error test cases ┃
-┡━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ spine01 │ 5            │ 1            │ 1            │ 0           │ ['VerifyCPUUtilization']           │
-│ spine02 │ 5            │ 1            │ 1            │ 0           │ ['VerifyCPUUtilization']           │
-│ leaf01  │ 6            │ 0            │ 1            │ 0           │ ['VerifyCPUUtilization']           │
-│ leaf02  │ 6            │ 0            │ 1            │ 0           │ ['VerifyCPUUtilization']           │
-│ leaf03  │ 6            │ 0            │ 1            │ 0           │ ['VerifyCPUUtilization']           │
-│ leaf04  │ 6            │ 0            │ 1            │ 0           │ ['VerifyCPUUtilization']           │
-└─────────┴──────────────┴──────────────┴──────────────┴─────────────┴────────────────────────────────────┘
+--- ANTA NRFU Run Information ---
+Number of devices: 3 (3 established)
+Total number of selected tests: 27
+---------------------------------
+                                            Summary per device
+┏━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Device ┃ # of success ┃ # of skipped ┃ # of failure ┃ # of errors ┃ List of failed or error test cases ┃
+┡━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ leaf1  │ 9            │ 0            │ 0            │ 0           │                                    │
+├────────┼──────────────┼──────────────┼──────────────┼─────────────┼────────────────────────────────────┤
+│ leaf2  │ 7            │ 1            │ 1            │ 0           │ VerifyAgentLogs                    │
+├────────┼──────────────┼──────────────┼──────────────┼─────────────┼────────────────────────────────────┤
+│ spine1 │ 9            │ 0            │ 0            │ 0           │                                    │
+└────────┴──────────────┴──────────────┴──────────────┴─────────────┴────────────────────────────────────┘
 ```
 
-## Use a single tag in CLI
+##### Single tag
 
-The most used approach is to use a single tag in your CLI to filter tests & devices configured with this one.
-
-In such scenario, ANTA will run tests marked with `$tag` only on devices marked with `$tag`. All other tests and devices will be ignored
+With a tag specified, only tests matching this tag will be run on matching devices.
 
 ```bash
-$ anta nrfu -c .personal/catalog-class.yml --tags leaf text
+$ anta nrfu --tags leaf text
 ╭────────────────────── Settings ──────────────────────╮
-│ Running ANTA tests:                                  │
-│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │
-│ - Tests catalog contains 10 tests                    │
+│ - ANTA Inventory contains 3 devices (AsyncEOSDevice) │
+│ - Tests catalog contains 11 tests                    │
 ╰──────────────────────────────────────────────────────╯
 
-leaf01 :: VerifyUptime :: SUCCESS
-leaf01 :: VerifyReloadCause :: SUCCESS
-leaf01 :: VerifyCPUUtilization :: SUCCESS
-leaf02 :: VerifyUptime :: SUCCESS
-leaf02 :: VerifyReloadCause :: SUCCESS
-leaf02 :: VerifyCPUUtilization :: SUCCESS
-leaf03 :: VerifyUptime :: SUCCESS
-leaf03 :: VerifyReloadCause :: SUCCESS
-leaf03 :: VerifyCPUUtilization :: SUCCESS
-leaf04 :: VerifyUptime :: SUCCESS
-leaf04 :: VerifyReloadCause :: SUCCESS
-leaf04 :: VerifyCPUUtilization :: SUCCESS
+--- ANTA NRFU Run Information ---
+Number of devices: 3 (2 established)
+Total number of selected tests: 6
+---------------------------------
+
+leaf1 :: VerifyReloadCause :: SUCCESS
+leaf1 :: VerifyUptime :: SUCCESS
+leaf1 :: VerifyMlagStatus :: SUCCESS
+leaf2 :: VerifyReloadCause :: SUCCESS
+leaf2 :: VerifyUptime :: SUCCESS
+leaf2 :: VerifyMlagStatus :: SKIPPED (MLAG is disabled)
 ```
 
-In this case, only `leaf` devices defined in your [inventory](#inventory-and-catalog-for-tests) are used to run tests marked with `leaf` in your [test catalog](#inventory-and-catalog-for-tests)
-
-## Use multiple tags in CLI
+In this case, only `leaf` devices defined in the inventory are used to run tests marked with the `leaf` in the test catalog.
 
-A more advanced usage of the tag feature is to list multiple tags in your CLI using `--tags $tag1,$tag2` syntax.
+##### Multiple tags
 
-In such scenario, all devices marked with `$tag1` will be selected and ANTA will run tests with `$tag1`, then devices with `$tag2` will be selected and will be tested with tests marked with `$tag2`
+It is possible to use multiple tags using the `--tags tag1,tag2` syntax.
 
 ```bash
-anta nrfu -c .personal/catalog-class.yml --tags leaf,fabric text
-
-spine01 :: VerifyUptime :: SUCCESS
-spine02 :: VerifyUptime :: SUCCESS
-leaf01 :: VerifyUptime :: SUCCESS
-leaf01 :: VerifyReloadCause :: SUCCESS
-leaf01 :: VerifyCPUUtilization :: SUCCESS
-leaf02 :: VerifyUptime :: SUCCESS
-leaf02 :: VerifyReloadCause :: SUCCESS
-leaf02 :: VerifyCPUUtilization :: SUCCESS
-leaf03 :: VerifyUptime :: SUCCESS
-leaf03 :: VerifyReloadCause :: SUCCESS
-leaf03 :: VerifyCPUUtilization :: SUCCESS
-leaf04 :: VerifyUptime :: SUCCESS
-leaf04 :: VerifyReloadCause :: SUCCESS
-leaf04 :: VerifyCPUUtilization :: SUCCESS
+anta nrfu --tags leaf,spine text
+╭────────────────────── Settings ──────────────────────╮
+│ - ANTA Inventory contains 3 devices (AsyncEOSDevice) │
+│ - Tests catalog contains 11 tests                    │
+╰──────────────────────────────────────────────────────╯
+
+--- ANTA NRFU Run Information ---
+Number of devices: 3 (3 established)
+Total number of selected tests: 15
+---------------------------------
+
+leaf1 :: VerifyReloadCause :: SUCCESS
+leaf1 :: VerifyMlagStatus :: SUCCESS
+leaf1 :: VerifyUptime :: SUCCESS
+leaf1 :: VerifyL3MTU :: SUCCESS
+leaf1 :: VerifyUptime :: SUCCESS
+leaf2 :: VerifyReloadCause :: SUCCESS
+leaf2 :: VerifyMlagStatus :: SKIPPED (MLAG is disabled)
+leaf2 :: VerifyUptime :: SUCCESS
+leaf2 :: VerifyL3MTU :: SUCCESS
+leaf2 :: VerifyUptime :: SUCCESS
+spine1 :: VerifyReloadCause :: SUCCESS
+spine1 :: VerifyMlagStatus :: SUCCESS
+spine1 :: VerifyUptime :: SUCCESS
+spine1 :: VerifyL3MTU :: SUCCESS
+spine1 :: VerifyUptime :: SUCCESS
 ```