diff options
Diffstat (limited to 'docs/cli')
| -rw-r--r-- | docs/cli/check.md | 15 | ||||
| -rw-r--r-- | docs/cli/debug.md | 21 | ||||
| -rw-r--r-- | docs/cli/exec.md | 9 | ||||
| -rw-r--r-- | docs/cli/get-inventory-information.md | 180 | ||||
| -rw-r--r-- | docs/cli/inv-from-ansible.md | 15 | ||||
| -rw-r--r-- | docs/cli/inv-from-cvp.md | 9 | ||||
| -rw-r--r-- | docs/cli/nrfu.md | 90 | ||||
| -rw-r--r-- | docs/cli/overview.md | 7 | ||||
| -rw-r--r-- | docs/cli/tag-management.md | 344 |
9 files changed, 385 insertions, 305 deletions
diff --git a/docs/cli/check.md b/docs/cli/check.md index d7dea62..c230722 100644 --- a/docs/cli/check.md +++ b/docs/cli/check.md @@ -1,11 +1,12 @@ +--- +anta_title: ANTA check commands +--- <!-- ~ 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. @@ -27,10 +28,12 @@ Commands: ```bash Usage: anta check catalog [OPTIONS] - Check that the catalog is valid + 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. + -c, --catalog FILE Path to the test catalog file [env var: + ANTA_CATALOG; required] + --catalog-format [yaml|json] Format of the catalog file, either 'yaml' or + 'json' [env var: ANTA_CATALOG_FORMAT] + --help Show this message and exit. ``` diff --git a/docs/cli/debug.md b/docs/cli/debug.md index db5f496..4c864db 100644 --- a/docs/cli/debug.md +++ b/docs/cli/debug.md @@ -1,11 +1,12 @@ +--- +anta_title: ANTA debug commands +--- <!-- ~ 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. @@ -14,7 +15,7 @@ The ANTA CLI includes a set of debugging tools, making it easier to build and te 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). + The `debug` tools require a device from your inventory. Thus, you must use a valid [ANTA Inventory](../usage-inventory-catalog.md#device-inventory). ## Executing an EOS command @@ -52,8 +53,6 @@ Options: ANTA_DISABLE_CACHE] -i, --inventory FILE Path to the inventory YAML file. [env var: ANTA_INVENTORY; required] - --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 @@ -97,8 +96,9 @@ Usage: anta debug run-template [OPTIONS] PARAMS... 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 + 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: @@ -125,8 +125,6 @@ Options: ANTA_DISABLE_CACHE] -i, --inventory FILE Path to the inventory YAML file. [env var: ANTA_INVENTORY; required] - --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 @@ -161,11 +159,12 @@ Run templated command 'show vlan {vlan_id}' with {'vlan_id': '10'} on DC1-LEAF1A '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 +!!! warning + If multiple arguments of the same key are provided, only the last argument value will be kept in the template parameters. + ```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'} diff --git a/docs/cli/exec.md b/docs/cli/exec.md index 061a19e..2eb12ee 100644 --- a/docs/cli/exec.md +++ b/docs/cli/exec.md @@ -1,14 +1,16 @@ +--- +anta_title: Executing Commands on Devices +--- <!-- ~ 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 +## EXEC command overview + ```bash anta exec --help Usage: anta exec [OPTIONS] COMMAND [ARGS]... @@ -133,6 +135,7 @@ json_format: text_format: - show bfd peers ``` + ### Example ```bash diff --git a/docs/cli/get-inventory-information.md b/docs/cli/get-inventory-information.md index 1831484..ab1bebc 100644 --- a/docs/cli/get-inventory-information.md +++ b/docs/cli/get-inventory-information.md @@ -1,14 +1,61 @@ +--- +anta_title: Retrieving Inventory Information +--- <!-- ~ 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 commands to access data from your local inventory. + +## 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 (visit [this page](tag-management.md) to learn more about tags). The `--connected` option allows to display only the devices where a connection has been established. + +### Command overview -The ANTA CLI offers multiple entrypoints to access data from your local inventory. +```bash +Usage: anta get inventory [OPTIONS] -## Inventory used of examples + 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 FLOAT Global API timeout. This value will be used + for all devices. [env var: ANTA_TIMEOUT; + default: 30.0] + --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] + --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 + By default, `anta get inventory` only provides information that doesn't rely on a device connection. If you are interested in obtaining connection-dependent details, like the hardware model, use the `--connected` option. + +### Example Let's consider the following inventory: @@ -65,123 +112,15 @@ anta_inventory: 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 -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 FLOAT Global API timeout. This value will be used for all - devices. [env var: ANTA_TIMEOUT; default: 30.0] - --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] - --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 -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 FLOAT Global API timeout. This value will be used - for all devices. [env var: ANTA_TIMEOUT; - default: 30.0] - --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] - --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 +$ anta get inventory --tags SPINE Current inventory content is: { 'DC1-SPINE1': AsyncEOSDevice( name='DC1-SPINE1', - tags=['SPINE', 'DC1'], + tags={'DC1-SPINE1', 'DC1', 'SPINE'}, hw_model=None, is_online=False, established=False, @@ -189,13 +128,12 @@ Current inventory content is: host='172.20.20.101', eapi_port=443, username='arista', - enable=True, - enable_password='arista', + enable=False, insecure=False ), 'DC1-SPINE2': AsyncEOSDevice( name='DC1-SPINE2', - tags=['SPINE', 'DC1'], + tags={'DC1', 'SPINE', 'DC1-SPINE2'}, hw_model=None, is_online=False, established=False, @@ -203,12 +141,12 @@ Current inventory content is: host='172.20.20.102', eapi_port=443, username='arista', - enable=True, + enable=False, insecure=False ), 'DC2-SPINE1': AsyncEOSDevice( name='DC2-SPINE1', - tags=['SPINE', 'DC2'], + tags={'DC2', 'DC2-SPINE1', 'SPINE'}, hw_model=None, is_online=False, established=False, @@ -216,12 +154,12 @@ Current inventory content is: host='172.20.20.201', eapi_port=443, username='arista', - enable=True, + enable=False, insecure=False ), 'DC2-SPINE2': AsyncEOSDevice( name='DC2-SPINE2', - tags=['SPINE', 'DC2'], + tags={'DC2', 'DC2-SPINE2', 'SPINE'}, hw_model=None, is_online=False, established=False, @@ -229,7 +167,7 @@ Current inventory content is: host='172.20.20.202', eapi_port=443, username='arista', - enable=True, + enable=False, insecure=False ) } diff --git a/docs/cli/inv-from-ansible.md b/docs/cli/inv-from-ansible.md index b2672e2..6bbaca9 100644 --- a/docs/cli/inv-from-ansible.md +++ b/docs/cli/inv-from-ansible.md @@ -1,14 +1,15 @@ +--- +anta_title: Create an Inventory from Ansible inventory +--- <!-- ~ 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 +## Command overview ```bash $ anta get from-ansible --help @@ -32,9 +33,8 @@ Options: !!! warning - `anta get from-ansible` does not support inline vaulted variables, comment them out to generate your inventory. - If the vaulted variable is necessary to build the inventory (e.g. `ansible_host`), it needs to be unvaulted for `from-ansible` command to work." - + `anta get from-ansible` does not support inline vaulted variables, comment them out to generate your inventory. + If the vaulted variable is necessary to build the inventory (e.g. `ansible_host`), it needs to be unvaulted for `from-ansible` command to work." The output is an inventory where the name of the container is added as a tag for each host: @@ -54,8 +54,7 @@ anta_inventory: 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 +## 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: diff --git a/docs/cli/inv-from-cvp.md b/docs/cli/inv-from-cvp.md index a37af62..9717870 100644 --- a/docs/cli/inv-from-cvp.md +++ b/docs/cli/inv-from-cvp.md @@ -1,17 +1,18 @@ +--- +anta_title: Create an Inventory from CloudVision +--- <!-- ~ 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. !!! info The current implementation only works with on-premises CloudVision instances, not with CloudVision as a Service (CVaaS). -### Command overview +## Command overview ```bash Usage: anta get from-cvp [OPTIONS] @@ -54,7 +55,7 @@ anta_inventory: !!! 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 +## 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: diff --git a/docs/cli/nrfu.md b/docs/cli/nrfu.md index 90b4a40..0f2b425 100644 --- a/docs/cli/nrfu.md +++ b/docs/cli/nrfu.md @@ -1,17 +1,20 @@ +--- +anta_title: Execute Network Readiness For Use (NRFU) Testing +--- <!-- ~ 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) +- [Text report](#performing-nrfu-with-text-rendering) +- [Table report](#performing-nrfu-with-table-rendering) +- [JSON report](#performing-nrfu-with-json-rendering) +- [Custom template report](#performing-nrfu-with-custom-reports) +- [CSV report](#performing-nrfu-and-saving-results-in-a-csv-file) +- [Markdown report](#performing-nrfu-and-saving-results-in-a-markdown-file) ## NRFU Command overview @@ -28,16 +31,7 @@ All commands under the `anta nrfu` namespace require a catalog yaml file specifi ### 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. +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. Refer to the [dedicated page](tag-management.md) for more information. ### Device and test filtering @@ -45,7 +39,7 @@ Options `--device` and `--test` can be used to target one or multiple devices an ### Hide results -Option `--hide` can be used to hide test results in the output based on their status. The option can be repeated. Example: `anta nrfu --hide error --hide skipped`. +Option `--hide` can be used to hide test results in the output or report file based on their status. The option can be repeated. Example: `anta nrfu --hide error --hide skipped`. ## Performing NRFU with text rendering @@ -67,6 +61,7 @@ Options: ```bash anta nrfu --device DC1-LEAF1A text ``` + { loading=lazy width="1600" } ## Performing NRFU with table rendering @@ -92,6 +87,7 @@ The `--group-by` option show a summarized view of the test results per host or p ```bash anta nrfu --tags LEAF table ``` + { loading=lazy width="1600" } For larger setups, you can also group the results by host or test to get a summarized view: @@ -99,11 +95,13 @@ For larger setups, you can also group the results by host or test to get a summa ```bash anta nrfu table --group-by device ``` + { loading=lazy width="1600" } ```bash anta nrfu table --group-by test ``` + { loading=lazy width="1600" } To get more specific information, it is possible to filter on a single device or a single test: @@ -111,16 +109,18 @@ To get more specific information, it is possible to filter on a single device or ```bash anta nrfu --device spine1 table ``` + { loading=lazy width="1600" } ```bash anta nrfu --test VerifyZeroTouch table ``` + { loading=lazy width="1600" } ## 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. +The JSON rendering command in NRFU testing will generate an output of all test results in JSON format. ### Command overview @@ -131,20 +131,66 @@ 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: + -o, --output FILE Path to save report as a JSON 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. +The `--output` option allows you to save the JSON report as a file. If specified, no output will be displayed in the terminal. This is useful for further processing or integration with other tools. ### Example ```bash anta nrfu --tags LEAF json ``` + { loading=lazy width="1600" } +## Performing NRFU and saving results in a CSV file + +The `csv` command in NRFU testing is useful for generating a CSV file with all tests result. This file can be easily analyzed and filtered by operator for reporting purposes. + +### Command overview + +```bash +anta nrfu csv --help +Usage: anta nrfu csv [OPTIONS] + + ANTA command to check network states with CSV result. + +Options: + --csv-output FILE Path to save report as a CSV file [env var: + ANTA_NRFU_CSV_CSV_OUTPUT] + --help Show this message and exit. +``` + +### Example + +{ loading=lazy width="1600" } + +## Performing NRFU and saving results in a Markdown file + +The `md-report` command in NRFU testing generates a comprehensive Markdown report containing various sections, including detailed statistics for devices and test categories. + +### Command overview + +```bash +anta nrfu md-report --help + +Usage: anta nrfu md-report [OPTIONS] + + ANTA command to check network state with Markdown report. + +Options: + --md-output FILE Path to save the report as a Markdown file [env var: + ANTA_NRFU_MD_REPORT_MD_OUTPUT; required] + --help Show this message and exit. +``` + +### Example + +{ loading=lazy width="1600" } + ## 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. @@ -164,6 +210,7 @@ Options: 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. @@ -173,6 +220,7 @@ The `--output` option allows you to choose the path where the final report will ```bash anta nrfu --tags LEAF tpl-report --template ./custom_template.j2 ``` + { loading=lazy width="1600" } The template `./custom_template.j2` is a simple Jinja2 template: @@ -183,7 +231,7 @@ The template `./custom_template.j2` is a simple Jinja2 template: {% 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). +The Jinja2 template has access to all `TestResult` elements and their values, as described in this [documentation](../api/result_manager_models.md#anta.result_manager.models.TestResult). You can also save the report result to a file using the `--output` option: diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 107976a..f1247b7 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -1,11 +1,12 @@ +--- +anta_title: Overview of ANTA's Command-Line Interface (CLI) +--- <!-- ~ 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. @@ -35,7 +36,7 @@ To set them as environment variables: export ANTA_USERNAME=admin export ANTA_PASSWORD=arista123 export ANTA_INVENTORY=inventory.yml -export ANTA_INVENTORY=tests.yml +export ANTA_CATALOG=tests.yml ``` Then, run the CLI without options: diff --git a/docs/cli/tag-management.md b/docs/cli/tag-management.md index 8c043d7..ad5ccf3 100644 --- a/docs/cli/tag-management.md +++ b/docs/cli/tag-management.md @@ -4,162 +4,250 @@ ~ that can be found in the LICENSE file. --> -# Tag management +ANTA commands can be used with a `--tags` option. This option **filters the inventory** with the specified tag(s) when running the command. -## Overview +Tags can also be used to **restrict a specific test** to a set of devices when using `anta nrfu`. -Some of the ANTA commands like `anta nrfu` command come with a `--tags` option. +## Defining tags -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. +### Device tags -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. +Device tags can be defined in the inventory: -The next table provides a short summary of the scope of tags using CLI +```yaml +anta_inventory: + hosts: + - name: leaf1 + host: leaf1.anta.arista.com + tags: ["leaf"] + - name: leaf2 + host: leaf2.anta.arista.com + tags: ["leaf"] + - name: spine1 + host: spine1.anta.arista.com + tags: ["spine"] +``` + +Each device also has its own name automatically added as a tag: + +```bash +$ anta get inventory +Current inventory content is: +{ + 'leaf1': AsyncEOSDevice( + name='leaf1', + tags={'leaf', 'leaf1'}, <-- + [...] + host='leaf1.anta.arista.com', + [...] + ), + 'leaf2': AsyncEOSDevice( + name='leaf2', + tags={'leaf', 'leaf2'}, <-- + [...] + host='leaf2.anta.arista.com', + [...] + ), + 'spine1': AsyncEOSDevice( + name='spine1', + tags={'spine1', 'spine'}, <-- + [...] + host='spine1.anta.arista.com', + [...] + ) +} +``` + +### Test tags + +Tags can be defined in the test catalog to restrict tests to tagged devices: + +```yaml +anta.tests.system: + - VerifyUptime: + minimum: 10 + filters: + tags: ['spine'] + - VerifyUptime: + minimum: 9 + filters: + tags: ['leaf'] + - VerifyReloadCause: + filters: + tags: ['spine', 'leaf'] + - VerifyCoredump: + - VerifyAgentLogs: + - VerifyCPUUtilization: + - VerifyMemoryUtilization: + - VerifyFileSystemUtilization: + - VerifyNTP: + +anta.tests.mlag: + - VerifyMlagStatus: + filters: + tags: ['leaf'] + +anta.tests.interfaces: + - VerifyL3MTU: + mtu: 1500 + filters: + tags: ['spine'] +``` + +> A tag used to filter a test can also be a device name + +!!! tip "Use different input values for a specific test" + Leverage tags to define different input values for a specific test. See the `VerifyUptime` example above. + +## Using tags | Command | Description | | ------- | ----------- | -| `none` | Run all tests on all devices according `tag` definition in your inventory and test catalog. And tests with no tag are executed on all devices| -| `--tags leaf` | Run all tests marked with `leaf` tag on all devices configured with `leaf` tag.<br/> All other tags are ignored | -| `--tags leaf,spine` | Run all tests marked with `leaf` tag on all devices configured with `leaf` tag.<br/>Run all tests marked with `spine` tag on all devices configured with `spine` tag.<br/> All other tags are ignored | - -## Inventory and Catalog for tests - -All commands in this page are based on the following inventory and test catalog. - -=== "Inventory" - - ```yaml - --- - anta_inventory: - hosts: - - host: 192.168.0.10 - name: spine01 - tags: ['fabric', 'spine'] - - host: 192.168.0.11 - name: spine02 - tags: ['fabric', 'spine'] - - host: 192.168.0.12 - name: leaf01 - tags: ['fabric', 'leaf'] - - host: 192.168.0.13 - name: leaf02 - tags: ['fabric', 'leaf'] - - host: 192.168.0.14 - name: leaf03 - tags: ['fabric', 'leaf'] - - host: 192.168.0.15 - name: leaf04 - tags: ['fabric', 'leaf' - ``` - -=== "Test Catalog" - - ```yaml - anta.tests.system: - - VerifyUptime: - minimum: 10 - filters: - tags: ['fabric'] - - VerifyReloadCause: - tags: ['leaf', spine'] - - VerifyCoredump: - - VerifyAgentLogs: - - VerifyCPUUtilization: - filters: - tags: ['spine', 'leaf'] - - VerifyMemoryUtilization: - - VerifyFileSystemUtilization: - - VerifyNTP: - - anta.tests.mlag: - - VerifyMlagStatus: - - - anta.tests.interfaces: - - VerifyL3MTU: - mtu: 1500 - filters: - tags: ['demo'] - ``` - -## Default tags - -By default, ANTA uses a default tag for both devices and tests. This default tag is `all` and it can be explicit if you want to make it visible in your inventory and also implicit since the framework injects this tag if it is not defined. - -So this command will run all tests from your catalog on all devices. With a mapping for `tags` defined in your inventory and catalog. If no `tags` configured, then tests are executed against all devices. +| No `--tags` option | Run all tests on all devices according to the `tag` definitions in your inventory and test catalog.<br/> Tests without tags are executed on all devices. | +| `--tags leaf` | Run all tests marked with the `leaf` tag on all devices configured with the `leaf` tag.<br/> All other tests are ignored. | +| `--tags leaf,spine` | Run all tests marked with the `leaf` tag on all devices configured with the `leaf` tag.<br/>Run all tests marked with the `spine` tag on all devices configured with the `spine` tag.<br/> All other tests are ignored. | + +### Examples + +The following examples use the inventory and test catalog defined above. + +#### No `--tags` option + +Tests without tags are run on all devices. +Tests with tags will only run on devices with matching tags. ```bash -$ anta nrfu -c .personal/catalog-class.yml table --group-by device +$ anta nrfu table --group-by device +╭────────────────────── Settings ──────────────────────╮ +│ - ANTA Inventory contains 3 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 11 tests │ +╰──────────────────────────────────────────────────────╯ + +--- ANTA NRFU Run Information --- +Number of devices: 3 (3 established) +Total number of selected tests: 27 +--------------------------------- + Summary per device +┏━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ +┃ Device ┃ # of success ┃ # of skipped ┃ # of failure ┃ # of errors ┃ List of failed or error test cases ┃ +┡━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ +│ leaf1 │ 9 │ 0 │ 0 │ 0 │ │ +├────────┼──────────────┼──────────────┼──────────────┼─────────────┼────────────────────────────────────┤ +│ leaf2 │ 7 │ 1 │ 1 │ 0 │ VerifyAgentLogs │ +├────────┼──────────────┼──────────────┼──────────────┼─────────────┼────────────────────────────────────┤ +│ spine1 │ 9 │ 0 │ 0 │ 0 │ │ +└────────┴──────────────┴──────────────┴──────────────┴─────────────┴────────────────────────────────────┘ +``` + +#### Single tag +With a tag specified, only tests matching this tag will be run on matching devices. + +```bash +$ anta nrfu --tags leaf text ╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ +│ - ANTA Inventory contains 3 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 11 tests │ ╰──────────────────────────────────────────────────────╯ -┏━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ -┃ Device ┃ # of success ┃ # of skipped ┃ # of failure ┃ # of errors ┃ List of failed or error test cases ┃ -┡━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ -│ spine01 │ 5 │ 1 │ 1 │ 0 │ ['VerifyCPUUtilization'] │ -│ spine02 │ 5 │ 1 │ 1 │ 0 │ ['VerifyCPUUtilization'] │ -│ leaf01 │ 6 │ 0 │ 1 │ 0 │ ['VerifyCPUUtilization'] │ -│ leaf02 │ 6 │ 0 │ 1 │ 0 │ ['VerifyCPUUtilization'] │ -│ leaf03 │ 6 │ 0 │ 1 │ 0 │ ['VerifyCPUUtilization'] │ -│ leaf04 │ 6 │ 0 │ 1 │ 0 │ ['VerifyCPUUtilization'] │ -└─────────┴──────────────┴──────────────┴──────────────┴─────────────┴────────────────────────────────────┘ +--- ANTA NRFU Run Information --- +Number of devices: 3 (2 established) +Total number of selected tests: 6 +--------------------------------- + +leaf1 :: VerifyReloadCause :: SUCCESS +leaf1 :: VerifyUptime :: SUCCESS +leaf1 :: VerifyMlagStatus :: SUCCESS +leaf2 :: VerifyReloadCause :: SUCCESS +leaf2 :: VerifyUptime :: SUCCESS +leaf2 :: VerifyMlagStatus :: SKIPPED (MLAG is disabled) ``` -## Use a single tag in CLI +In this case, only `leaf` devices defined in the inventory are used to run tests marked with the `leaf` in the test catalog. -The most used approach is to use a single tag in your CLI to filter tests & devices configured with this one. +#### Multiple tags -In such scenario, ANTA will run tests marked with `$tag` only on devices marked with `$tag`. All other tests and devices will be ignored +It is possible to use multiple tags using the `--tags tag1,tag2` syntax. ```bash -$ anta nrfu -c .personal/catalog-class.yml --tags leaf text +$ anta nrfu --tags leaf,spine text ╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ +│ - ANTA Inventory contains 3 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 11 tests │ ╰──────────────────────────────────────────────────────╯ -leaf01 :: VerifyUptime :: SUCCESS -leaf01 :: VerifyReloadCause :: SUCCESS -leaf01 :: VerifyCPUUtilization :: SUCCESS -leaf02 :: VerifyUptime :: SUCCESS -leaf02 :: VerifyReloadCause :: SUCCESS -leaf02 :: VerifyCPUUtilization :: SUCCESS -leaf03 :: VerifyUptime :: SUCCESS -leaf03 :: VerifyReloadCause :: SUCCESS -leaf03 :: VerifyCPUUtilization :: SUCCESS -leaf04 :: VerifyUptime :: SUCCESS -leaf04 :: VerifyReloadCause :: SUCCESS -leaf04 :: VerifyCPUUtilization :: SUCCESS +--- ANTA NRFU Run Information --- +Number of devices: 3 (3 established) +Total number of selected tests: 15 +--------------------------------- + +leaf1 :: VerifyReloadCause :: SUCCESS +leaf1 :: VerifyMlagStatus :: SUCCESS +leaf1 :: VerifyUptime :: SUCCESS +leaf1 :: VerifyL3MTU :: SUCCESS +leaf1 :: VerifyUptime :: SUCCESS +leaf2 :: VerifyReloadCause :: SUCCESS +leaf2 :: VerifyMlagStatus :: SKIPPED (MLAG is disabled) +leaf2 :: VerifyUptime :: SUCCESS +leaf2 :: VerifyL3MTU :: SUCCESS +leaf2 :: VerifyUptime :: SUCCESS +spine1 :: VerifyReloadCause :: SUCCESS +spine1 :: VerifyMlagStatus :: SUCCESS +spine1 :: VerifyUptime :: SUCCESS +spine1 :: VerifyL3MTU :: SUCCESS +spine1 :: VerifyUptime :: SUCCESS ``` -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) +## Obtaining all configured tags + +As most ANTA commands accommodate tag filtering, this command is useful for enumerating all tags configured in the inventory. Running the `anta get tags` command will return a list of all tags configured in the inventory. -## Use multiple tags in CLI +### Command overview + +```bash +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 FLOAT Global API timeout. This value will be used for all + devices. [env var: ANTA_TIMEOUT; default: 30.0] + --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] + --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3. [env var: ANTA_TAGS] + --help Show this message and exit. +``` -A more advanced usage of the tag feature is to list multiple tags in your CLI using `--tags $tag1,$tag2` syntax. +### Example -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` +To get the list of all configured tags in the inventory, run the following command: ```bash -anta nrfu -c .personal/catalog-class.yml --tags leaf,fabric text - -spine01 :: VerifyUptime :: SUCCESS -spine02 :: VerifyUptime :: SUCCESS -leaf01 :: VerifyUptime :: SUCCESS -leaf01 :: VerifyReloadCause :: SUCCESS -leaf01 :: VerifyCPUUtilization :: SUCCESS -leaf02 :: VerifyUptime :: SUCCESS -leaf02 :: VerifyReloadCause :: SUCCESS -leaf02 :: VerifyCPUUtilization :: SUCCESS -leaf03 :: VerifyUptime :: SUCCESS -leaf03 :: VerifyReloadCause :: SUCCESS -leaf03 :: VerifyCPUUtilization :: SUCCESS -leaf04 :: VerifyUptime :: SUCCESS -leaf04 :: VerifyReloadCause :: SUCCESS -leaf04 :: VerifyCPUUtilization :: SUCCESS +$ anta get tags +Tags found: +[ + "leaf", + "leaf1", + "leaf2", + "spine", + "spine1" +] ``` |