diff options
Diffstat (limited to 'docs/cli')
| -rw-r--r-- | docs/cli/check.md | 36 | ||||
| -rw-r--r-- | docs/cli/debug.md | 175 | ||||
| -rw-r--r-- | docs/cli/exec.md | 298 | ||||
| -rw-r--r-- | docs/cli/get-inventory-information.md | 237 | ||||
| -rw-r--r-- | docs/cli/inv-from-ansible.md | 72 | ||||
| -rw-r--r-- | docs/cli/inv-from-cvp.md | 72 | ||||
| -rw-r--r-- | docs/cli/nrfu.md | 247 | ||||
| -rw-r--r-- | docs/cli/overview.md | 103 | ||||
| -rw-r--r-- | docs/cli/tag-management.md | 165 |
9 files changed, 1405 insertions, 0 deletions
diff --git a/docs/cli/check.md b/docs/cli/check.md new file mode 100644 index 0000000..d7dea62 --- /dev/null +++ b/docs/cli/check.md @@ -0,0 +1,36 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# ANTA check commands + +The ANTA check command allow to execute some checks on the ANTA input files. +Only checking the catalog is currently supported. + +```bash +anta check --help +Usage: anta check [OPTIONS] COMMAND [ARGS]... + + Check commands for building ANTA + +Options: + --help Show this message and exit. + +Commands: + catalog Check that the catalog is valid +``` + +## Checking the catalog + +```bash +Usage: anta check catalog [OPTIONS] + + Check that the catalog is valid + +Options: + -c, --catalog FILE Path to the test catalog YAML file [env var: + ANTA_CATALOG; required] + --help Show this message and exit. +``` diff --git a/docs/cli/debug.md b/docs/cli/debug.md new file mode 100644 index 0000000..1743c7a --- /dev/null +++ b/docs/cli/debug.md @@ -0,0 +1,175 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# ANTA debug commands + +The ANTA CLI includes a set of debugging tools, making it easier to build and test ANTA content. This functionality is accessed via the `debug` subcommand and offers the following options: + +- Executing a command on a device from your inventory and retrieving the result. +- Running a templated command on a device from your inventory and retrieving the result. + +These tools are especially helpful in building the tests, as they give a visual access to the output received from the eAPI. They also facilitate the extraction of output content for use in unit tests, as described in our [contribution guide](../contribution.md). + +!!! warning + The `debug` tools require a device from your inventory. Thus, you MUST use a valid [ANTA Inventory](../usage-inventory-catalog.md#create-an-inventory-file). + +## Executing an EOS command + +You can use the `run-cmd` entrypoint to run a command, which includes the following options: + +### Command overview + +```bash +$ anta debug run-cmd --help +Usage: anta debug run-cmd [OPTIONS] + + Run arbitrary command to an ANTA device + +Options: + -u, --username TEXT Username to connect to EOS [env var: + ANTA_USERNAME; required] + -p, --password TEXT Password to connect to EOS that must be provided. + It can be prompted using '--prompt' option. [env + var: ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. It + can be prompted using '--prompt' option. Requires + '--enable' option. [env var: + ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC + mode. This option tries to access this mode before + sending a command to the device. [env var: + ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not provided. + [env var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT; + default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + --ofmt [json|text] EOS eAPI format to use. can be text or json + -v, --version [1|latest] EOS eAPI version + -r, --revision INTEGER eAPI command revision + -d, --device TEXT Device from inventory to use [required] + -c, --command TEXT Command to run [required] + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +### Example + +This example illustrates how to run the `show interfaces description` command with a `JSON` format (default): + +```bash +anta debug run-cmd --command "show interfaces description" --device DC1-SPINE1 +Run command show interfaces description on DC1-SPINE1 +{ + 'interfaceDescriptions': { + 'Ethernet1': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-LEAF1A_Ethernet1', 'interfaceStatus': 'up'}, + 'Ethernet2': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-LEAF1B_Ethernet1', 'interfaceStatus': 'up'}, + 'Ethernet3': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-BL1_Ethernet1', 'interfaceStatus': 'up'}, + 'Ethernet4': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-BL2_Ethernet1', 'interfaceStatus': 'up'}, + 'Loopback0': {'lineProtocolStatus': 'up', 'description': 'EVPN_Overlay_Peering', 'interfaceStatus': 'up'}, + 'Management0': {'lineProtocolStatus': 'up', 'description': 'oob_management', 'interfaceStatus': 'up'} + } +} +``` + +## Executing an EOS command using templates + +The `run-template` entrypoint allows the user to provide an [`f-string`](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python) templated command. It is followed by a list of arguments (key-value pairs) that build a dictionary used as template parameters. + +### Command overview + +```bash +$ anta debug run-template --help +Usage: anta debug run-template [OPTIONS] PARAMS... + + Run arbitrary templated command to an ANTA device. + + Takes a list of arguments (keys followed by a value) to build a dictionary + used as template parameters. Example: + + anta debug run-template -d leaf1a -t 'show vlan {vlan_id}' vlan_id 1 + +Options: + -u, --username TEXT Username to connect to EOS [env var: + ANTA_USERNAME; required] + -p, --password TEXT Password to connect to EOS that must be provided. + It can be prompted using '--prompt' option. [env + var: ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. It + can be prompted using '--prompt' option. Requires + '--enable' option. [env var: + ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC + mode. This option tries to access this mode before + sending a command to the device. [env var: + ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not provided. + [env var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT; + default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + --ofmt [json|text] EOS eAPI format to use. can be text or json + -v, --version [1|latest] EOS eAPI version + -r, --revision INTEGER eAPI command revision + -d, --device TEXT Device from inventory to use [required] + -t, --template TEXT Command template to run. E.g. 'show vlan + {vlan_id}' [required] + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +### Example + +This example uses the `show vlan {vlan_id}` command in a `JSON` format: + +```bash +anta debug run-template --template "show vlan {vlan_id}" vlan_id 10 --device DC1-LEAF1A +Run templated command 'show vlan {vlan_id}' with {'vlan_id': '10'} on DC1-LEAF1A +{ + 'vlans': { + '10': { + 'name': 'VRFPROD_VLAN10', + 'dynamic': False, + 'status': 'active', + 'interfaces': { + 'Cpu': {'privatePromoted': False, 'blocked': None}, + 'Port-Channel11': {'privatePromoted': False, 'blocked': None}, + 'Vxlan1': {'privatePromoted': False, 'blocked': None} + } + } + }, + 'sourceDetail': '' +} +``` +!!! warning + If multiple arguments of the same key are provided, only the last argument value will be kept in the template parameters. + +### Example of multiple arguments + +```bash +anta -log DEBUG debug run-template --template "ping {dst} source {src}" dst "8.8.8.8" src Loopback0 --device DC1-SPINE1 +> {'dst': '8.8.8.8', 'src': 'Loopback0'} + +anta -log DEBUG debug run-template --template "ping {dst} source {src}" dst "8.8.8.8" src Loopback0 dst "1.1.1.1" src Loopback1 --device DC1-SPINE1 +> {'dst': '1.1.1.1', 'src': 'Loopback1'} +# Notice how `src` and `dst` keep only the latest value +``` diff --git a/docs/cli/exec.md b/docs/cli/exec.md new file mode 100644 index 0000000..fe39c12 --- /dev/null +++ b/docs/cli/exec.md @@ -0,0 +1,298 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# Executing Commands on Devices + +ANTA CLI provides a set of entrypoints to facilitate remote command execution on EOS devices. + +### EXEC Command overview +```bash +anta exec --help +Usage: anta exec [OPTIONS] COMMAND [ARGS]... + + Execute commands to inventory devices + +Options: + --help Show this message and exit. + +Commands: + clear-counters Clear counter statistics on EOS devices + collect-tech-support Collect scheduled tech-support from EOS devices + snapshot Collect commands output from devices in inventory +``` + +## Clear interfaces counters + +This command clears interface counters on EOS devices specified in your inventory. + +### Command overview + +```bash +anta exec clear-counters --help +Usage: anta exec clear-counters [OPTIONS] + + Clear counter statistics on EOS devices + +Options: + -u, --username TEXT Username to connect to EOS [env var: ANTA_USERNAME; + required] + -p, --password TEXT Password to connect to EOS that must be provided. It + can be prompted using '--prompt' option. [env var: + ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. It can + be prompted using '--prompt' option. Requires '-- + enable' option. [env var: ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC mode. + This option tries to access this mode before sending + a command to the device. [env var: ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not provided. [env + var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT; + default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +### Example + +```bash +anta exec clear-counters --tags SPINE +[20:19:13] INFO Connecting to devices... utils.py:43 + INFO Clearing counters on remote devices... utils.py:46 + INFO Cleared counters on DC1-SPINE2 (cEOSLab) utils.py:41 + INFO Cleared counters on DC2-SPINE1 (cEOSLab) utils.py:41 + INFO Cleared counters on DC1-SPINE1 (cEOSLab) utils.py:41 + INFO Cleared counters on DC2-SPINE2 (cEOSLab) +``` + +## Collect a set of commands + +This command collects all the commands specified in a commands-list file, which can be in either `json` or `text` format. + +### Command overview + +```bash +anta exec snapshot --help +Usage: anta exec snapshot [OPTIONS] + + Collect commands output from devices in inventory + +Options: + -u, --username TEXT Username to connect to EOS [env var: + ANTA_USERNAME; required] + -p, --password TEXT Password to connect to EOS that must be provided. + It can be prompted using '--prompt' option. [env + var: ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. It + can be prompted using '--prompt' option. Requires + '--enable' option. [env var: + ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC + mode. This option tries to access this mode before + sending a command to the device. [env var: + ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not provided. + [env var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT; + default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + -c, --commands-list FILE File with list of commands to collect [env var: + ANTA_EXEC_SNAPSHOT_COMMANDS_LIST; required] + -o, --output DIRECTORY Directory to save commands output. [env var: + ANTA_EXEC_SNAPSHOT_OUTPUT; default: + anta_snapshot_2023-12-06_09_22_11] + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +The commands-list file should follow this structure: + +```yaml +--- +json_format: + - show version +text_format: + - show bfd peers +``` +### Example + +```bash +anta exec snapshot --tags SPINE --commands-list ./commands.yaml --output ./ +[20:25:15] INFO Connecting to devices... utils.py:78 + INFO Collecting commands from remote devices utils.py:81 + INFO Collected command 'show version' from device DC2-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show version' from device DC2-SPINE2 (cEOSLab) utils.py:76 + INFO Collected command 'show version' from device DC1-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show version' from device DC1-SPINE2 (cEOSLab) utils.py:76 +[20:25:16] INFO Collected command 'show bfd peers' from device DC2-SPINE2 (cEOSLab) utils.py:76 + INFO Collected command 'show bfd peers' from device DC2-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show bfd peers' from device DC1-SPINE1 (cEOSLab) utils.py:76 + INFO Collected command 'show bfd peers' from device DC1-SPINE2 (cEOSLab) +``` + +The results of the executed commands will be stored in the output directory specified during command execution: + +```bash +tree _2023-07-14_20_25_15 +_2023-07-14_20_25_15 +├── DC1-SPINE1 +│ ├── json +│ │ └── show version.json +│ └── text +│ └── show bfd peers.log +├── DC1-SPINE2 +│ ├── json +│ │ └── show version.json +│ └── text +│ └── show bfd peers.log +├── DC2-SPINE1 +│ ├── json +│ │ └── show version.json +│ └── text +│ └── show bfd peers.log +└── DC2-SPINE2 + ├── json + │ └── show version.json + └── text + └── show bfd peers.log + +12 directories, 8 files +``` + +## Get Scheduled tech-support + +EOS offers a feature that automatically creates a tech-support archive every hour by default. These archives are stored under `/mnt/flash/schedule/tech-support`. + +```eos +leaf1#show schedule summary +Maximum concurrent jobs 1 +Prepend host name to logfile: Yes +Name At Time Last Interval Timeout Max Max Logfile Location Status + Time (mins) (mins) Log Logs + Files Size +----------------- ------------- ----------- -------------- ------------- ----------- ---------- --------------------------------- ------ +tech-support now 08:37 60 30 100 - flash:schedule/tech-support/ Success + + +leaf1#bash ls /mnt/flash/schedule/tech-support +leaf1_tech-support_2023-03-09.1337.log.gz leaf1_tech-support_2023-03-10.0837.log.gz leaf1_tech-support_2023-03-11.0337.log.gz +``` + +For Network Readiness for Use (NRFU) tests and to keep a comprehensive report of the system state before going live, ANTA provides a command-line interface that efficiently retrieves these files. + +### Command overview + +```bash +anta exec collect-tech-support --help +Usage: anta exec collect-tech-support [OPTIONS] + + Collect scheduled tech-support from EOS devices + +Options: + -u, --username TEXT Username to connect to EOS [env var: ANTA_USERNAME; + required] + -p, --password TEXT Password to connect to EOS that must be provided. It + can be prompted using '--prompt' option. [env var: + ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. It can + be prompted using '--prompt' option. Requires '-- + enable' option. [env var: ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC mode. + This option tries to access this mode before sending + a command to the device. [env var: ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not provided. [env + var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT; + default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + -o, --output PATH Path for test catalog [default: ./tech-support] + --latest INTEGER Number of scheduled show-tech to retrieve + --configure Ensure devices have 'aaa authorization exec default + local' configured (required for SCP on EOS). THIS + WILL CHANGE THE CONFIGURATION OF YOUR NETWORK. + --help Show this message and exit. +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +When executed, this command fetches tech-support files and downloads them locally into a device-specific subfolder within the designated folder. You can specify the output folder with the `--output` option. + +ANTA uses SCP to download files from devices and will not trust unknown SSH hosts by default. Add the SSH public keys of your devices to your `known_hosts` file or use the `anta --insecure` option to ignore SSH host keys validation. + +The configuration `aaa authorization exec default` must be present on devices to be able to use SCP. +ANTA can automatically configure `aaa authorization exec default local` using the `anta exec collect-tech-support --configure` option. +If you require specific AAA configuration for `aaa authorization exec default`, like `aaa authorization exec default none` or `aaa authorization exec default group tacacs+`, you will need to configure it manually. + +The `--latest` option allows retrieval of a specific number of the most recent tech-support files. + +!!! warning + By default **all** the tech-support files present on the devices are retrieved. + +### Example + +```bash +anta --insecure exec collect-tech-support +[15:27:19] INFO Connecting to devices... +INFO Copying '/mnt/flash/schedule/tech-support/spine1_tech-support_2023-06-09.1315.log.gz' from device spine1 to 'tech-support/spine1' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf3_tech-support_2023-06-09.1315.log.gz' from device leaf3 to 'tech-support/leaf3' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf1_tech-support_2023-06-09.1315.log.gz' from device leaf1 to 'tech-support/leaf1' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf2_tech-support_2023-06-09.1315.log.gz' from device leaf2 to 'tech-support/leaf2' locally +INFO Copying '/mnt/flash/schedule/tech-support/spine2_tech-support_2023-06-09.1315.log.gz' from device spine2 to 'tech-support/spine2' locally +INFO Copying '/mnt/flash/schedule/tech-support/leaf4_tech-support_2023-06-09.1315.log.gz' from device leaf4 to 'tech-support/leaf4' locally +INFO Collected 1 scheduled tech-support from leaf2 +INFO Collected 1 scheduled tech-support from spine2 +INFO Collected 1 scheduled tech-support from leaf3 +INFO Collected 1 scheduled tech-support from spine1 +INFO Collected 1 scheduled tech-support from leaf1 +INFO Collected 1 scheduled tech-support from leaf4 +``` + +The output folder structure is as follows: + +```bash +tree tech-support/ +tech-support/ +├── leaf1 +│ └── leaf1_tech-support_2023-06-09.1315.log.gz +├── leaf2 +│ └── leaf2_tech-support_2023-06-09.1315.log.gz +├── leaf3 +│ └── leaf3_tech-support_2023-06-09.1315.log.gz +├── leaf4 +│ └── leaf4_tech-support_2023-06-09.1315.log.gz +├── spine1 +│ └── spine1_tech-support_2023-06-09.1315.log.gz +└── spine2 + └── spine2_tech-support_2023-06-09.1315.log.gz + +6 directories, 6 files +``` + +Each device has its own subdirectory containing the collected tech-support files. diff --git a/docs/cli/get-inventory-information.md b/docs/cli/get-inventory-information.md new file mode 100644 index 0000000..70100fe --- /dev/null +++ b/docs/cli/get-inventory-information.md @@ -0,0 +1,237 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# Retrieving Inventory Information + +The ANTA CLI offers multiple entrypoints to access data from your local inventory. + +## Inventory used of examples + +Let's consider the following inventory: + +```yaml +--- +anta_inventory: + hosts: + - host: 172.20.20.101 + name: DC1-SPINE1 + tags: ["SPINE", "DC1"] + + - host: 172.20.20.102 + name: DC1-SPINE2 + tags: ["SPINE", "DC1"] + + - host: 172.20.20.111 + name: DC1-LEAF1A + tags: ["LEAF", "DC1"] + + - host: 172.20.20.112 + name: DC1-LEAF1B + tags: ["LEAF", "DC1"] + + - host: 172.20.20.121 + name: DC1-BL1 + tags: ["BL", "DC1"] + + - host: 172.20.20.122 + name: DC1-BL2 + tags: ["BL", "DC1"] + + - host: 172.20.20.201 + name: DC2-SPINE1 + tags: ["SPINE", "DC2"] + + - host: 172.20.20.202 + name: DC2-SPINE2 + tags: ["SPINE", "DC2"] + + - host: 172.20.20.211 + name: DC2-LEAF1A + tags: ["LEAF", "DC2"] + + - host: 172.20.20.212 + name: DC2-LEAF1B + tags: ["LEAF", "DC2"] + + - host: 172.20.20.221 + name: DC2-BL1 + tags: ["BL", "DC2"] + + - host: 172.20.20.222 + name: DC2-BL2 + tags: ["BL", "DC2"] +``` + +## Obtaining all configured tags + +As most of ANTA's commands accommodate tag filtering, this particular command is useful for enumerating all tags configured in the inventory. Running the `anta get tags` command will return a list of all tags that have been configured in the inventory. + +### Command overview + +```bash +anta get tags --help +Usage: anta get tags [OPTIONS] + + Get list of configured tags in user inventory. + +Options: + -u, --username TEXT Username to connect to EOS [env var: ANTA_USERNAME; + required] + -p, --password TEXT Password to connect to EOS that must be provided. It + can be prompted using '--prompt' option. [env var: + ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. It can + be prompted using '--prompt' option. Requires '-- + enable' option. [env var: ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC mode. + This option tries to access this mode before sending + a command to the device. [env var: ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not provided. [env + var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT; + default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + --help Show this message and exit. +``` + +### Example + +To get the list of all configured tags in the inventory, run the following command: + +```bash +anta get tags +Tags found: +[ + "BL", + "DC1", + "DC2", + "LEAF", + "SPINE" +] + +* note that tag all has been added by anta +``` + +!!! note + Even if you haven't explicitly configured the `all` tag in the inventory, it is automatically added. This default tag allows to execute commands on all devices in the inventory when no tag is specified. + +## List devices in inventory + +This command will list all devices available in the inventory. Using the `--tags` option, you can filter this list to only include devices with specific tags. The `--connected` option allows to display only the devices where a connection has been established. + +### Command overview + +```bash +anta get inventory --help +Usage: anta get inventory [OPTIONS] + + Show inventory loaded in ANTA. + +Options: + -u, --username TEXT Username to connect to EOS [env var: + ANTA_USERNAME; required] + -p, --password TEXT Password to connect to EOS that must be + provided. It can be prompted using '--prompt' + option. [env var: ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. + It can be prompted using '--prompt' option. + Requires '--enable' option. [env var: + ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC + mode. This option tries to access this mode + before sending a command to the device. [env + var: ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not + provided. [env var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: + ANTA_TIMEOUT; default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + --connected / --not-connected Display inventory after connection has been + created + --help Show this message and exit. +``` + + +!!! tip + In its default mode, `anta get inventory` provides only information that doesn't rely on a device connection. If you are interested in obtaining connection-dependent details, like the hardware model, please use the `--connected` option. + +### Example + +To retrieve a comprehensive list of all devices along with their details, execute the following command. It will provide all the data loaded into the ANTA inventory from your [inventory file](../usage-inventory-catalog.md). + +```bash +anta get inventory --tags SPINE +Current inventory content is: +{ + 'DC1-SPINE1': AsyncEOSDevice( + name='DC1-SPINE1', + tags=['SPINE', 'DC1'], + hw_model=None, + is_online=False, + established=False, + disable_cache=False, + host='172.20.20.101', + eapi_port=443, + username='arista', + enable=True, + enable_password='arista', + insecure=False + ), + 'DC1-SPINE2': AsyncEOSDevice( + name='DC1-SPINE2', + tags=['SPINE', 'DC1'], + hw_model=None, + is_online=False, + established=False, + disable_cache=False, + host='172.20.20.102', + eapi_port=443, + username='arista', + enable=True, + insecure=False + ), + 'DC2-SPINE1': AsyncEOSDevice( + name='DC2-SPINE1', + tags=['SPINE', 'DC2'], + hw_model=None, + is_online=False, + established=False, + disable_cache=False, + host='172.20.20.201', + eapi_port=443, + username='arista', + enable=True, + insecure=False + ), + 'DC2-SPINE2': AsyncEOSDevice( + name='DC2-SPINE2', + tags=['SPINE', 'DC2'], + hw_model=None, + is_online=False, + established=False, + disable_cache=False, + host='172.20.20.202', + eapi_port=443, + username='arista', + enable=True, + insecure=False + ) +} +``` diff --git a/docs/cli/inv-from-ansible.md b/docs/cli/inv-from-ansible.md new file mode 100644 index 0000000..bb944d4 --- /dev/null +++ b/docs/cli/inv-from-ansible.md @@ -0,0 +1,72 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# Create an Inventory from Ansible inventory + +In large setups, it might be beneficial to construct your inventory based on your Ansible inventory. The `from-ansible` entrypoint of the `get` command enables the user to create an ANTA inventory from Ansible. + +### Command overview + +```bash +$ anta get from-ansible --help +Usage: anta get from-ansible [OPTIONS] + + Build ANTA inventory from an ansible inventory YAML file + +Options: + -g, --ansible-group TEXT Ansible group to filter + --ansible-inventory FILENAME + Path to your ansible inventory file to read + -o, --output FILENAME Path to save inventory file + -d, --inventory-directory PATH Directory to save inventory file + --help Show this message and exit. +``` + +The output is an inventory where the name of the container is added as a tag for each host: + +```yaml +anta_inventory: + hosts: + - host: 10.73.252.41 + name: srv-pod01 + - host: 10.73.252.42 + name: srv-pod02 + - host: 10.73.252.43 + name: srv-pod03 +``` + +!!! warning + The current implementation only considers devices directly attached to a specific Ansible group and does not support inheritence when using the `--ansible-group` option. + +By default, if user does not provide `--output` file, anta will save output to configured anta inventory (`anta --inventory`). If the output file has content, anta will ask user to overwrite when running in interactive console. This mechanism can be controlled by triggers in case of CI usage: `--overwrite` to force anta to overwrite file. If not set, anta will exit + + +### Command output + +`host` value is coming from the `ansible_host` key in your inventory while `name` is the name you defined for your host. Below is an ansible inventory example used to generate previous inventory: + +```yaml +--- +tooling: + children: + endpoints: + hosts: + srv-pod01: + ansible_httpapi_port: 9023 + ansible_port: 9023 + ansible_host: 10.73.252.41 + type: endpoint + srv-pod02: + ansible_httpapi_port: 9024 + ansible_port: 9024 + ansible_host: 10.73.252.42 + type: endpoint + srv-pod03: + ansible_httpapi_port: 9025 + ansible_port: 9025 + ansible_host: 10.73.252.43 + type: endpoint +``` diff --git a/docs/cli/inv-from-cvp.md b/docs/cli/inv-from-cvp.md new file mode 100644 index 0000000..8897370 --- /dev/null +++ b/docs/cli/inv-from-cvp.md @@ -0,0 +1,72 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# Create an Inventory from CloudVision + +In large setups, it might be beneficial to construct your inventory based on CloudVision. The `from-cvp` entrypoint of the `get` command enables the user to create an ANTA inventory from CloudVision. + +### Command overview + +```bash +anta get from-cvp --help +Usage: anta get from-cvp [OPTIONS] + + Build ANTA inventory from Cloudvision + +Options: + -ip, --cvp-ip TEXT CVP IP Address [required] + -u, --cvp-username TEXT CVP Username [required] + -p, --cvp-password TEXT CVP Password / token [required] + -c, --cvp-container TEXT Container where devices are configured + -d, --inventory-directory PATH Path to save inventory file + --help Show this message and exit. +``` + +The output is an inventory where the name of the container is added as a tag for each host: + +```yaml +anta_inventory: + hosts: + - host: 192.168.0.13 + name: leaf2 + tags: + - pod1 + - host: 192.168.0.15 + name: leaf4 + tags: + - pod2 +``` + +!!! warning + The current implementation only considers devices directly attached to a specific container when using the `--cvp-container` option. + +### Creating an inventory from multiple containers + +If you need to create an inventory from multiple containers, you can use a bash command and then manually concatenate files to create a single inventory file: + +```bash +$ for container in pod01 pod02 spines; do anta get from-cvp -ip <cvp-ip> -u cvpadmin -p cvpadmin -c $container -d test-inventory; done + +[12:25:35] INFO Getting auth token from cvp.as73.inetsix.net for user tom +[12:25:36] INFO Creating inventory folder /home/tom/Projects/arista/network-test-automation/test-inventory + WARNING Using the new api_token parameter. This will override usage of the cvaas_token parameter if both are provided. This is because api_token and cvaas_token parameters + are for the same use case and api_token is more generic + INFO Connected to CVP cvp.as73.inetsix.net + + +[12:25:37] INFO Getting auth token from cvp.as73.inetsix.net for user tom +[12:25:38] WARNING Using the new api_token parameter. This will override usage of the cvaas_token parameter if both are provided. This is because api_token and cvaas_token parameters + are for the same use case and api_token is more generic + INFO Connected to CVP cvp.as73.inetsix.net + + +[12:25:38] INFO Getting auth token from cvp.as73.inetsix.net for user tom +[12:25:39] WARNING Using the new api_token parameter. This will override usage of the cvaas_token parameter if both are provided. This is because api_token and cvaas_token parameters + are for the same use case and api_token is more generic + INFO Connected to CVP cvp.as73.inetsix.net + + INFO Inventory file has been created in /home/tom/Projects/arista/network-test-automation/test-inventory/inventory-spines.yml +``` diff --git a/docs/cli/nrfu.md b/docs/cli/nrfu.md new file mode 100644 index 0000000..6dcc393 --- /dev/null +++ b/docs/cli/nrfu.md @@ -0,0 +1,247 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# Execute Network Readiness For Use (NRFU) Testing + +ANTA provides a set of commands for performing NRFU tests on devices. These commands are under the `anta nrfu` namespace and offer multiple output format options: + +- [Text view](#performing-nrfu-with-text-rendering) +- [Table view](#performing-nrfu-with-table-rendering) +- [JSON view](#performing-nrfu-with-json-rendering) +- [Custom template view](#performing-nrfu-with-custom-reports) + +### NRFU Command overview + +```bash +anta nrfu --help +Usage: anta nrfu [OPTIONS] COMMAND [ARGS]... + + Run NRFU against inventory devices + +Options: + -u, --username TEXT Username to connect to EOS [env var: ANTA_USERNAME; + required] + -p, --password TEXT Password to connect to EOS that must be provided. It + can be prompted using '--prompt' option. [env var: + ANTA_PASSWORD] + --enable-password TEXT Password to access EOS Privileged EXEC mode. It can + be prompted using '--prompt' option. Requires '-- + enable' option. [env var: ANTA_ENABLE_PASSWORD] + --enable Some commands may require EOS Privileged EXEC mode. + This option tries to access this mode before sending + a command to the device. [env var: ANTA_ENABLE] + -P, --prompt Prompt for passwords if they are not provided. [env + var: ANTA_PROMPT] + --timeout INTEGER Global connection timeout [env var: ANTA_TIMEOUT; + default: 30] + --insecure Disable SSH Host Key validation [env var: + ANTA_INSECURE] + --disable-cache Disable cache globally [env var: + ANTA_DISABLE_CACHE] + -i, --inventory FILE Path to the inventory YAML file [env var: + ANTA_INVENTORY; required] + -t, --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3 [env var: ANTA_TAGS] + -c, --catalog FILE Path to the test catalog YAML file [env var: + ANTA_CATALOG; required] + --ignore-status Always exit with success [env var: + ANTA_NRFU_IGNORE_STATUS] + --ignore-error Only report failures and not errors [env var: + ANTA_NRFU_IGNORE_ERROR] + --help Show this message and exit. + +Commands: + json ANTA command to check network state with JSON result + table ANTA command to check network states with table result + text ANTA command to check network states with text result + tpl-report ANTA command to check network state with templated report +``` + +> `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices + +All commands under the `anta nrfu` namespace require a catalog yaml file specified with the `--catalog` option and a device inventory file specified with the `--inventory` option. + +!!! info + Issuing the command `anta nrfu` will run `anta nrfu table` without any option. + +## Tag management + +The `--tags` option can be used to target specific devices in your inventory and run only tests configured with this specific tags from your catalog. The default tag is set to `all` and is implicit. Expected behaviour is provided below: + +| 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 | + +!!! info + [More examples](tag-management.md) available on this dedicated page. + +## Performing NRFU with text rendering + +The `text` subcommand provides a straightforward text report for each test executed on all devices in your inventory. + +### Command overview + +```bash +anta nrfu text --help +Usage: anta nrfu text [OPTIONS] + + ANTA command to check network states with text result + +Options: + -s, --search TEXT Regular expression to search in both name and test + --skip-error Hide tests in errors due to connectivity issue + --help Show this message and exit. +``` + +The `--search` option permits filtering based on a regular expression pattern in both the hostname and the test name. + +The `--skip-error` option can be used to exclude tests that failed due to connectivity issues or unsupported commands. + +### Example + +```bash +anta nrfu text --tags LEAF --search DC1-LEAF1A +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-text-output.png) + +## Performing NRFU with table rendering + +The `table` command under the `anta nrfu` namespace offers a clear and organized table view of the test results, suitable for filtering. It also has its own set of options for better control over the output. + +### Command overview + +```bash +anta nrfu table --help +Usage: anta nrfu table [OPTIONS] + + ANTA command to check network states with table result + +Options: + -d, --device TEXT Show a summary for this device + -t, --test TEXT Show a summary for this test + --group-by [device|test] Group result by test or host. default none + --help Show this message and exit. +``` + +The `--device` and `--test` options show a summarized view of the test results for a specific host or test case, respectively. + +The `--group-by` option show a summarized view of the test results per host or per test. + +### Examples + +```bash +anta nrfu --tags LEAF table +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-table-output.png) + +For larger setups, you can also group the results by host or test to get a summarized view: + +```bash +anta nrfu table --group-by device +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-table-group-by-host-output.png) + +```bash +anta nrfu table --group-by test +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-table-group-by-test-output.png) + +To get more specific information, it is possible to filter on a single device or a single test: + +```bash +anta nrfu table --device spine1 +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-table-filter-host-output.png) + +```bash +anta nrfu table --test VerifyZeroTouch +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-table-filter-test-output.png) + +## Performing NRFU with JSON rendering + +The JSON rendering command in NRFU testing is useful in generating a JSON output that can subsequently be passed on to another tool for reporting purposes. + +### Command overview + +```bash +anta nrfu json --help +Usage: anta nrfu json [OPTIONS] + + ANTA command to check network state with JSON result + +Options: + -o, --output FILE Path to save report as a file [env var: + ANTA_NRFU_JSON_OUTPUT] + --help Show this message and exit. +``` + +The `--output` option allows you to save the JSON report as a file. + +### Example + +```bash +anta nrfu --tags LEAF json +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-json-output.png) + +## Performing NRFU with custom reports + +ANTA offers a CLI option for creating custom reports. This leverages the Jinja2 template system, allowing you to tailor reports to your specific needs. + +### Command overview + +```bash +anta nrfu tpl-report --help +Usage: anta nrfu tpl-report [OPTIONS] + + ANTA command to check network state with templated report + +Options: + -tpl, --template FILE Path to the template to use for the report [env var: + ANTA_NRFU_TPL_REPORT_TEMPLATE; required] + -o, --output FILE Path to save report as a file [env var: + ANTA_NRFU_TPL_REPORT_OUTPUT] + --help Show this message and exit. +``` +The `--template` option is used to specify the Jinja2 template file for generating the custom report. + +The `--output` option allows you to choose the path where the final report will be saved. + +### Example + +```bash +anta nrfu --tags LEAF tpl-report --template ./custom_template.j2 +``` +[{ loading=lazy width="1600" }](../imgs/anta-nrfu-tpl-report-output.png) + +The template `./custom_template.j2` is a simple Jinja2 template: + +```j2 +{% for d in data %} +* {{ d.test }} is [green]{{ d.result | upper}}[/green] for {{ d.name }} +{% endfor %} +``` + +The Jinja2 template has access to all `TestResult` elements and their values, as described in this [documentation](../api/result_manager_models.md#testresult-entry). + +You can also save the report result to a file using the `--output` option: + +```bash +anta nrfu --tags LEAF tpl-report --template ./custom_template.j2 --output nrfu-tpl-report.txt +``` + +The resulting output might look like this: + +```bash +cat nrfu-tpl-report.txt +* VerifyMlagStatus is [green]SUCCESS[/green] for DC1-LEAF1A +* VerifyMlagInterfaces is [green]SUCCESS[/green] for DC1-LEAF1A +* VerifyMlagConfigSanity is [green]SUCCESS[/green] for DC1-LEAF1A +* VerifyMlagReloadDelay is [green]SUCCESS[/green] for DC1-LEAF1A +``` diff --git a/docs/cli/overview.md b/docs/cli/overview.md new file mode 100644 index 0000000..90e70a5 --- /dev/null +++ b/docs/cli/overview.md @@ -0,0 +1,103 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# Overview of ANTA's Command-Line Interface (CLI) + +ANTA provides a powerful Command-Line Interface (CLI) to perform a wide range of operations. This document provides a comprehensive overview of ANTA CLI usage and its commands. + +ANTA can also be used as a Python library, allowing you to build your own tools based on it. Visit this [page](../advanced_usages/as-python-lib.md) for more details. + +To start using the ANTA CLI, open your terminal and type `anta`. + +!!! warning + The ANTA CLI options have changed after version 0.11 and have moved away from the top level `anta` and are now required at their respective commands (e.g. `anta nrfu`). This breaking change occurs after users feedback on making the CLI more intuitive. This change should not affect user experience when using environment variables. + +## Invoking ANTA CLI + +```bash +$ anta --help +--8<-- "anta_help.txt" +``` + +## ANTA environement variables + +Certain parameters are required and can be either passed to the ANTA CLI or set as an environment variable (ENV VAR). + +To pass the parameters via the CLI: + +```bash +anta nrfu -u admin -p arista123 -i inventory.yaml -c tests.yaml +``` + +To set them as environment variables: + +```bash +export ANTA_USERNAME=admin +export ANTA_PASSWORD=arista123 +export ANTA_INVENTORY=inventory.yml +export ANTA_INVENTORY=tests.yml +``` + +Then, run the CLI without options: + +```bash +anta nrfu +``` + +!!! note + All environement variables may not be needed for every commands. + Refer to `<command> --help` for the comprehensive environment varibles names. + +Below are the environement variables usable with the `anta nrfu` command: + +| Variable Name | Purpose | Required | +| ------------- | ------- |----------| +| ANTA_USERNAME | The username to use in the inventory to connect to devices. | Yes | +| ANTA_PASSWORD | The password to use in the inventory to connect to devices. | Yes | +| ANTA_INVENTORY | The path to the inventory file. | Yes | +| ANTA_CATALOG | The path to the catalog file. | Yes | +| ANTA_PROMPT | The value to pass to the prompt for password is password is not provided | No | +| ANTA_INSECURE | Whether or not using insecure mode when connecting to the EOS devices HTTP API. | No | +| ANTA_DISABLE_CACHE | A variable to disable caching for all ANTA tests (enabled by default). | No | +| ANTA_ENABLE | Whether it is necessary to go to enable mode on devices. | No | +| ANTA_ENABLE_PASSWORD | The optional enable password, when this variable is set, ANTA_ENABLE or `--enable` is required. | No | + +!!! info + Caching can be disabled with the global parameter `--disable-cache`. For more details about how caching is implemented in ANTA, please refer to [Caching in ANTA](../advanced_usages/caching.md). + +## ANTA Exit Codes + +ANTA CLI utilizes the following exit codes: + +- `Exit code 0` - All tests passed successfully. +- `Exit code 1` - An internal error occurred while executing ANTA. +- `Exit code 2` - A usage error was raised. +- `Exit code 3` - Tests were run, but at least one test returned an error. +- `Exit code 4` - Tests were run, but at least one test returned a failure. + +To ignore the test status, use `anta nrfu --ignore-status`, and the exit code will always be 0. + +To ignore errors, use `anta nrfu --ignore-error`, and the exit code will be 0 if all tests succeeded or 1 if any test failed. + +## Shell Completion + +You can enable shell completion for the ANTA CLI: + +=== "ZSH" + + If you use ZSH shell, add the following line in your `~/.zshrc`: + + ```bash + eval "$(_ANTA_COMPLETE=zsh_source anta)" > /dev/null + ``` + +=== "BASH" + + With bash, add the following line in your `~/.bashrc`: + + ```bash + eval "$(_ANTA_COMPLETE=bash_source anta)" > /dev/null + ``` diff --git a/docs/cli/tag-management.md b/docs/cli/tag-management.md new file mode 100644 index 0000000..8c043d7 --- /dev/null +++ b/docs/cli/tag-management.md @@ -0,0 +1,165 @@ +<!-- + ~ Copyright (c) 2023-2024 Arista Networks, Inc. + ~ Use of this source code is governed by the Apache License 2.0 + ~ that can be found in the LICENSE file. + --> + +# Tag management + +## Overview + +Some of the ANTA commands like `anta nrfu` command come with a `--tags` option. + +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. + +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. + +The next table provides a short summary of the scope of tags using CLI + +| 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. + +```bash +$ anta nrfu -c .personal/catalog-class.yml table --group-by device + +╭────────────────────── Settings ──────────────────────╮ +│ Running ANTA tests: │ +│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 10 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'] │ +└─────────┴──────────────┴──────────────┴──────────────┴─────────────┴────────────────────────────────────┘ +``` + +## Use a single tag in CLI + +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 + +```bash +$ anta nrfu -c .personal/catalog-class.yml --tags leaf text +╭────────────────────── Settings ──────────────────────╮ +│ Running ANTA tests: │ +│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 10 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 +``` + +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 + +A more advanced usage of the tag feature is to list multiple tags in your CLI using `--tags $tag1,$tag2` syntax. + +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` + +```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 +``` |