arista/anta
1
0
Fork 0
Code Issues Activity

Adding upstream version 0.13.0.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-05 11:32:35 +01:00
parent c0ae77e0f6
commit ecf5ca3300
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
272 changed files with 33172 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/cli/check.md Normal file
View file

@ -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.
```

175
docs/cli/debug.md Normal file
View file

@ -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
```

298
docs/cli/exec.md Normal file
View file

@ -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.

237
docs/cli/get-inventory-information.md Normal file
View file

@ -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
)
}
```

72
docs/cli/inv-from-ansible.md Normal file
View file

@ -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
```

72
docs/cli/inv-from-cvp.md Normal file
View file

@ -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
```

247
docs/cli/nrfu.md Normal file
View file

@ -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
```
[![anta nrfu text results](../imgs/anta-nrfu-text-output.png){ 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
```
[![anta nrfu table results](../imgs/anta-nrfu-table-output.png){ 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
```
[![anta nrfu table group_by_host_output](../imgs/anta-nrfu-table-group-by-host-output.png){ loading=lazy width="1600" }](../imgs/anta-nrfu-table-group-by-host-output.png)
```bash
anta nrfu table --group-by test
```
[![anta nrfu table group_by_test_output](../imgs/anta-nrfu-table-group-by-test-output.png){ 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
```
[![anta nrfu table filter_host_output](../imgs/anta-nrfu-table-filter-host-output.png){ loading=lazy width="1600" }](../imgs/anta-nrfu-table-filter-host-output.png)
```bash
anta nrfu table --test VerifyZeroTouch
```
[![anta nrfu table filter_test_output](../imgs/anta-nrfu-table-filter-test-output.png){ 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
```
[![anta nrfu json results](../imgs/anta-nrfu-json-output.png){ 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
```
[![anta nrfu json results](../imgs/anta-nrfu-tpl-report-output.png){ 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
```

103
docs/cli/overview.md Normal file
View file

@ -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
```

165
docs/cli/tag-management.md Normal file
View file

@ -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
```