diff --git a/.github/markdownlint.yaml b/.github/markdownlint.yaml new file mode 100644 index 000000000..1804cf75d --- /dev/null +++ b/.github/markdownlint.yaml @@ -0,0 +1,98 @@ +# markdownlint configuration +# the definitive list of rules for markdownlint can be found: +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# +# only deviations from the defaults are noted here or where there's an opinion +# being expressed. + +# default state for all rules +default: + true + +# heading style +MD003: + style: "atx" + +# unordered list style +MD004: + style: "dash" + +# unorderd list indentation (2-spaces) +# keep it tight yo! +MD007: + indent: 2 + +# line length +MD013: + false + # a lot of debate whether to wrap or not wrap + +# multiple headings with the same content +# siblings_only is set here to allow for common header values in structured +# documents +MD024: + siblings_only: true + +# Multiple top-level headings in the same document +MD025: + front_matter_title: "" + +# MD029/ol-prefix - Ordered list item prefix +MD029: + # List style + style: "ordered" + +# fenced code should be surrounded by blank lines default: true +MD031: + true + +# lists should be surrounded by blank lines default: true +MD032: + true + +# MD033/no-inline-html - Inline HTML +MD033: + false + +# bare URL - bare URLs should be wrapped in angle brackets +# +MD034: + false + +# horizontal rule style default: consistent +MD035: + style: "---" + +# first line in a file to be a top-level heading +# since we're using front-matter, this +MD041: + false + +# proper-names - proper names to have the correct capitalization +# probably not entirely helpful in a technical writing environment. +MD044: + false + +# block style - disabled to allow for admonitions +MD046: + false + +# MD048/code-fence-style - Code fence style +MD048: + # Code fence style + style: "backtick" + +# MD049/Emphasis style should be consistent +MD049: + # Emphasis style should be consistent + style: "asterisk" + +# MD050/Strong style should be consistent +MD050: + # Strong style should be consistent + style: "asterisk" + +# MD037/no-space-in-emphasis - Spaces inside emphasis markers +# This incorrectly catches stars used in table contents, so *foo | *bar is triggered to remove the space between | and *bar. +MD037: + false diff --git a/.github/markdownlintignore b/.github/markdownlintignore new file mode 100644 index 000000000..e69de29bb diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7a895170e..244270375 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -95,3 +95,13 @@ repos: - types-pyOpenSSL - pytest files: ^(anta|tests)/ + + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.41.0 + hooks: + - id: markdownlint + name: Check Markdown files style. + args: + - --config=.github/markdownlint.yaml + - --ignore-path=.github/markdownlintignore + - --fix diff --git a/anta/runner.py b/anta/runner.py index 12f549daa..dcb2d962e 100644 --- a/anta/runner.py +++ b/anta/runner.py @@ -89,7 +89,7 @@ async def setup_inventory(inventory: AntaInventory, tags: set[str] | None, devic devices Devices on which to run tests. None means all devices. established_only - If True use return only devices where a connection is established. + If True use return only devices where a connection is established. Returns ------- diff --git a/docs/README.md b/docs/README.md index 4f11feebe..07ac3d28b 100755 --- a/docs/README.md +++ b/docs/README.md @@ -39,7 +39,9 @@ If you plan to use ANTA only as a CLI tool you can use `pipx` to install it. [`pipx`](https://pipx.pypa.io/stable/) is a tool to install and run python applications in isolated environments. Refer to `pipx` instructions to install on your system. `pipx` installs ANTA in an isolated python environment and makes it available globally. + **This is not recommended if you plan to contribute to ANTA** + ```bash # Install ANTA CLI with pipx diff --git a/docs/advanced_usages/as-python-lib.md b/docs/advanced_usages/as-python-lib.md index d8790f3ef..d64104a95 100644 --- a/docs/advanced_usages/as-python-lib.md +++ b/docs/advanced_usages/as-python-lib.md @@ -32,7 +32,6 @@ It uses the [aio-eapi](https://github.com/jeremyschulman/aio-eapi) eAPI client a The [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) class is a subclass of the standard Python type [dict](https://docs.python.org/3/library/stdtypes.html#dict). The keys of this dictionary are the device names, the values are [AntaDevice](../api/device.md#anta.device.AntaDevice) instances. - [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) provides methods to interact with the ANTA inventory: - The [add_device()](../api/inventory.md#anta.inventory.AntaInventory.add_device) method adds an [AntaDevice](../api/device.md#anta.device.AntaDevice) instance to the inventory. Adding an entry to [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) with a key different from the device name is not allowed. @@ -42,13 +41,11 @@ The [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) class is a ## Examples -##### Parse an ANTA inventory file - -> This script parses an ANTA inventory file, connects to devices and print their status +### Parse an ANTA inventory file ```python """ -Example +This script parses an ANTA inventory file, connects to devices and print their status. """ import asyncio @@ -84,13 +81,11 @@ if __name__ == "__main__": ??? note "How to create your inventory file" Please visit this [dedicated section](../usage-inventory-catalog.md) for how to use inventory and catalog files. -##### Run EOS commands - -> This script runs a list of EOS commands on reachable devices +### Run EOS commands ```python """ -Example +This script runs a list of EOS commands on reachable devices. """ # This is needed to run the script for python < 3.10 for typing annotations from __future__ import annotations diff --git a/docs/advanced_usages/caching.md b/docs/advanced_usages/caching.md index 7de310de7..8b089cec3 100644 --- a/docs/advanced_usages/caching.md +++ b/docs/advanced_usages/caching.md @@ -10,7 +10,7 @@ ANTA is a streamlined Python framework designed for efficient interaction with n By default, ANTA utilizes [aiocache](https://github.com/aio-libs/aiocache)'s memory cache backend, also called [`SimpleMemoryCache`](https://aiocache.aio-libs.org/en/v0.12.2/caches.html#simplememorycache). This library aims for simplicity and supports asynchronous operations to go along with Python `asyncio` used in ANTA. -The `_init_cache()` method of the [AntaDevice](../advanced_usages/as-python-lib.md#antadevice-abstract-class) abstract class initializes the cache. Child classes can override this method to tweak the cache configuration: +The `_init_cache()` method of the [AntaDevice](../api/device.md#anta.device.AntaDevice) abstract class initializes the cache. Child classes can override this method to tweak the cache configuration: ```python def _init_cache(self) -> None: @@ -29,7 +29,7 @@ The cache is initialized per `AntaDevice` and uses the following cache key desig `:` -The `uid` is an attribute of [AntaCommand](../advanced_usages/as-python-lib.md#antacommand-class), which is a unique identifier generated from the command, version, revision and output format. +The `uid` is an attribute of [AntaCommand](../api/models.md#anta.models.AntaCommand), which is a unique identifier generated from the command, version, revision and output format. Each UID has its own asyncio lock. This design allows coroutines that need to access the cache for different UIDs to do so concurrently. The locks are managed by the `self.cache_locks` dictionary. @@ -44,10 +44,13 @@ Caching is enabled by default in ANTA following the previous configuration and m There might be scenarios where caching is not wanted. You can disable caching in multiple ways in ANTA: 1. Caching can be disabled globally, for **ALL** commands on **ALL** devices, using the `--disable-cache` global flag when invoking anta at the [CLI](../cli/overview.md#invoking-anta-cli): + ```bash anta --disable-cache --username arista --password arista nrfu table ``` + 2. Caching can be disabled per device, network or range by setting the `disable_cache` key to `True` when defining the ANTA [Inventory](../usage-inventory-catalog.md#device-inventory) file: + ```yaml anta_inventory: hosts: @@ -69,9 +72,10 @@ There might be scenarios where caching is not wanted. You can disable caching in end: 172.22.22.19 disable_cache: True ``` + This approach effectively disables caching for **ALL** commands sent to devices targeted by the `disable_cache` key. -3. For tests developers, caching can be disabled for a specific [`AntaCommand`](../advanced_usages/as-python-lib.md#antacommand-class) or [`AntaTemplate`](../advanced_usages/as-python-lib.md#antatemplate-class) by setting the `use_cache` attribute to `False`. That means the command output will always be collected on the device and therefore, never use caching. +3. For tests developers, caching can be disabled for a specific [`AntaCommand`](../api/models.md#anta.models.AntaCommand) or [`AntaTemplate`](../api/models.md#anta.models.AntaTemplate) by setting the `use_cache` attribute to `False`. That means the command output will always be collected on the device and therefore, never use caching. ### Disable caching in a child class of `AntaDevice` diff --git a/docs/advanced_usages/custom-tests.md b/docs/advanced_usages/custom-tests.md index 958a05539..d81f32dcf 100644 --- a/docs/advanced_usages/custom-tests.md +++ b/docs/advanced_usages/custom-tests.md @@ -4,7 +4,7 @@ ~ that can be found in the LICENSE file. --> -!!! info "" +!!! info This documentation applies for both creating tests in ANTA or creating your own test package. ANTA is not only a Python library with a CLI and a collection of built-in tests, it is also a framework you can extend by building your own tests. @@ -64,7 +64,7 @@ Full AntaTest API documentation is available in the [API documentation section]( - `name` (`str`): Name of the test. Used during reporting. - `description` (`str`): A human readable description of your test. - `categories` (`list[str]`): A list of categories in which the test belongs. -- `commands` (`[list[AntaCommand | AntaTemplate]]`): A list of command to collect from devices. This list __must__ be a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) or [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances. Rendering [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances will be discussed later. +- `commands` (`[list[AntaCommand | AntaTemplate]]`): A list of command to collect from devices. This list **must** be a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) or [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances. Rendering [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances will be discussed later. !!! info All these class attributes are mandatory. If any attribute is missing, a `NotImplementedError` exception will be raised during class instantiation. @@ -87,7 +87,6 @@ Full AntaTest API documentation is available in the [API documentation section]( show_root_toc_entry: false heading_level: 10 - !!! note "Logger object" ANTA already provides comprehensive logging at every steps of a test execution. The [AntaTest](../api/models.md#anta.models.AntaTest) class also provides a `logger` attribute that is a Python logger specific to the test instance. See [Python documentation](https://docs.python.org/3/library/logging.html) for more information. @@ -140,8 +139,8 @@ Full `ResultOverwrite` model documentation is available in [API documentation se ### Methods -- [test(self) -> None](../api/models.md#anta.models.AntaTest.test): This is an abstract method that __must__ be implemented. It contains the test logic that can access the collected command outputs using the `instance_commands` instance attribute, access the test inputs using the `inputs` instance attribute and __must__ set the `result` instance attribute accordingly. It must be implemented using the `AntaTest.anta_test` decorator that provides logging and will collect commands before executing the `test()` method. -- [render(self, template: AntaTemplate) -> list[AntaCommand]](../api/models.md#anta.models.AntaTest.render): This method only needs to be implemented if [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances are present in the `commands` class attribute. It will be called for every [AntaTemplate](../api/models.md#anta.models.AntaTemplate) occurrence and __must__ return a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) using the [AntaTemplate.render()](../api/models.md#anta.models.AntaTemplate.render) method. It can access test inputs using the `inputs` instance attribute. +- [test(self) -> None](../api/models.md#anta.models.AntaTest.test): This is an abstract method that **must** be implemented. It contains the test logic that can access the collected command outputs using the `instance_commands` instance attribute, access the test inputs using the `inputs` instance attribute and **must** set the `result` instance attribute accordingly. It must be implemented using the `AntaTest.anta_test` decorator that provides logging and will collect commands before executing the `test()` method. +- [render(self, template: AntaTemplate) -> list[AntaCommand]](../api/models.md#anta.models.AntaTest.render): This method only needs to be implemented if [AntaTemplate](../api/models.md#anta.models.AntaTemplate) instances are present in the `commands` class attribute. It will be called for every [AntaTemplate](../api/models.md#anta.models.AntaTemplate) occurrence and **must** return a list of [AntaCommand](../api/models.md#anta.models.AntaCommand) using the [AntaTemplate.render()](../api/models.md#anta.models.AntaTemplate.render) method. It can access test inputs using the `inputs` instance attribute. ## Test execution @@ -201,9 +200,9 @@ class (AntaTest): !!! tip "Command revision and version" * Most of EOS commands return a JSON structure according to a model (some commands may not be modeled hence the necessity to use `text` outformat sometimes. - * The model can change across time (adding feature, ... ) and when the model is changed in a non backward-compatible way, the __revision__ number is bumped. The initial model starts with __revision__ 1. - * A __revision__ applies to a particular CLI command whereas a __version__ is global to an eAPI call. The __version__ is internally translated to a specific __revision__ for each CLI command in the RPC call. The currently supported __version__ values are `1` and `latest`. - * A __revision takes precedence over a version__ (e.g. if a command is run with version="latest" and revision=1, the first revision of the model is returned) + * The model can change across time (adding feature, ... ) and when the model is changed in a non backward-compatible way, the **revision** number is bumped. The initial model starts with **revision** 1. + * A **revision** applies to a particular CLI command whereas a **version** is global to an eAPI call. The **version** is internally translated to a specific **revision** for each CLI command in the RPC call. The currently supported **version** values are `1` and `latest`. + * A **revision takes precedence over a version** (e.g. if a command is run with version="latest" and revision=1, the first revision of the model is returned) * By default, eAPI returns the first revision of each model to ensure that when upgrading, integrations with existing tools are not broken. This is done by using by default `version=1` in eAPI calls. By default, ANTA uses `version="latest"` in AntaCommand, but when developing tests, the revision MUST be provided when the outformat of the command is `json`. As explained earlier, this is to ensure that the eAPI always returns the same output model and that the test remains always valid from the day it was created. For some commands, you may also want to run them with a different revision or version. @@ -277,6 +276,7 @@ class (AntaTest): ``` The logic usually includes the following different stages: + 1. Parse the command outputs using the `self.instance_commands` instance attribute. 2. If needed, access the test inputs using the `self.inputs` instance attribute and write your conditional logic. 3. Set the `result` instance attribute to reflect the test result by either calling `self.result.is_success()` or `self.result.is_failure("")`. Sometimes, setting the test result to `skipped` using `self.result.is_skipped("")` can make sense (e.g. testing the OSPF neighbor states but no neighbor was found). However, you should not need to catch any exception and set the test result to `error` since the error handling is done by the framework, see below. @@ -357,6 +357,7 @@ anta_custom.dc_project: - VerifyFeatureX: minimum: 1 ``` + And now you can run your NRFU tests with the CLI: ```bash diff --git a/docs/api/catalog.md b/docs/api/catalog.md index fc719eacc..44cc4dfb7 100644 --- a/docs/api/catalog.md +++ b/docs/api/catalog.md @@ -5,6 +5,7 @@ --> ### ::: anta.catalog.AntaCatalog + options: filters: ["!^_[^_]", "!__str__"] diff --git a/docs/api/device.md b/docs/api/device.md index 9401f59af..136fec75b 100644 --- a/docs/api/device.md +++ b/docs/api/device.md @@ -6,18 +6,20 @@ # AntaDevice base class -![](../imgs/uml/anta.device.AntaDevice.jpeg) +![AntaDevice UML model](../imgs/uml/anta.device.AntaDevice.jpeg) ## ::: anta.device.AntaDevice + options: filters: ["!^_[^_]", "!__(eq|rich_repr)__", "_collect"] # Async EOS device class -![](../imgs/uml/anta.device.AsyncEOSDevice.jpeg) +![AsyncEOSDevice UML model](../imgs/uml/anta.device.AsyncEOSDevice.jpeg) ## ::: anta.device.AsyncEOSDevice + options: filters: ["!^_[^_]", "!__(eq|rich_repr)__", "_collect"] diff --git a/docs/api/inventory.md b/docs/api/inventory.md index 5e4400cfc..b826b9ff5 100644 --- a/docs/api/inventory.md +++ b/docs/api/inventory.md @@ -5,6 +5,7 @@ --> ### ::: anta.inventory.AntaInventory + options: filters: ["!^_[^_]", "!__str__"] diff --git a/docs/api/models.md b/docs/api/models.md index 3175fce54..1b360de98 100644 --- a/docs/api/models.md +++ b/docs/api/models.md @@ -6,17 +6,18 @@ # Test definition -![](../imgs/uml/anta.models.AntaTest.jpeg) +![AntaTest UML model](../imgs/uml/anta.models.AntaTest.jpeg) + +## ::: anta.models.AntaTest -### ::: anta.models.AntaTest options: filters: ["!^_[^_]", "!__init_subclass__", "!update_progress"] # Command definition -![](../imgs/uml/anta.models.AntaCommand.jpeg) +![AntaCommand UML model](../imgs/uml/anta.models.AntaCommand.jpeg) -### ::: anta.models.AntaCommand +## ::: anta.models.AntaCommand !!! warning CLI commands are protected to avoid execution of critical commands such as `reload` or `write erase`. @@ -27,6 +28,6 @@ # Template definition -![](../imgs/uml/anta.models.AntaTemplate.jpeg) +![AntaTemplate UML model](../imgs/uml/anta.models.AntaTemplate.jpeg) -### ::: anta.models.AntaTemplate +## ::: anta.models.AntaTemplate diff --git a/docs/api/result_manager.md b/docs/api/result_manager.md index dca0a19dd..9fc978a0b 100644 --- a/docs/api/result_manager.md +++ b/docs/api/result_manager.md @@ -6,8 +6,9 @@ # Result Manager definition -![](../imgs/uml/anta.result_manager.ResultManager.jpeg) +![ResultManager UML model](../imgs/uml/anta.result_manager.ResultManager.jpeg) + +## ::: anta.result_manager.ResultManager -### ::: anta.result_manager.ResultManager options: filters: ["!^_[^_]", "!^__len__"] diff --git a/docs/api/result_manager_models.md b/docs/api/result_manager_models.md index d0ccc7983..42e264899 100644 --- a/docs/api/result_manager_models.md +++ b/docs/api/result_manager_models.md @@ -6,8 +6,9 @@ # Test Result model -![](../imgs/uml/anta.result_manager.models.TestResult.jpeg) +![TestResult UML model](../imgs/uml/anta.result_manager.models.TestResult.jpeg) + +## ::: anta.result_manager.models.TestResult -### ::: anta.result_manager.models.TestResult options: filters: ["!^_[^_]", "!__str__"] diff --git a/docs/api/runner.md b/docs/api/runner.md index 27fbaa235..a2de00758 100644 --- a/docs/api/runner.md +++ b/docs/api/runner.md @@ -5,5 +5,6 @@ --> ### ::: anta.runner + options: filters: ["!^_[^_]", "!__str__"] diff --git a/docs/api/tests.md b/docs/api/tests.md index 2775a01ee..1ca4cb7b3 100644 --- a/docs/api/tests.md +++ b/docs/api/tests.md @@ -1,11 +1,12 @@ +--- +anta_title: ANTA Tests Landing Page +--- -# ANTA Tests Landing Page - This section describes all the available tests provided by the ANTA package. ## Available Tests diff --git a/docs/api/types.md b/docs/api/types.md index 806ab6308..a633e0430 100644 --- a/docs/api/types.md +++ b/docs/api/types.md @@ -5,6 +5,7 @@ --> ### ::: anta.custom_types + options: show_if_no_docstring: true show_root_full_path: true diff --git a/docs/cli/check.md b/docs/cli/check.md index 257ac73d8..c230722bb 100644 --- a/docs/cli/check.md +++ b/docs/cli/check.md @@ -1,11 +1,12 @@ +--- +anta_title: ANTA check commands +--- -# ANTA check commands - The ANTA check command allow to execute some checks on the ANTA input files. Only checking the catalog is currently supported. diff --git a/docs/cli/debug.md b/docs/cli/debug.md index b0b8a164f..60ac74f69 100644 --- a/docs/cli/debug.md +++ b/docs/cli/debug.md @@ -1,11 +1,12 @@ +--- +anta_title: ANTA debug commands +--- -# 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. @@ -158,6 +159,7 @@ 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. diff --git a/docs/cli/exec.md b/docs/cli/exec.md index 061a19e1f..2eb12eec5 100644 --- a/docs/cli/exec.md +++ b/docs/cli/exec.md @@ -1,14 +1,16 @@ +--- +anta_title: Executing Commands on Devices +--- -# 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 1831484a0..6fe9dc94d 100644 --- a/docs/cli/get-inventory-information.md +++ b/docs/cli/get-inventory-information.md @@ -1,11 +1,12 @@ +--- +anta_title: Retrieving Inventory Information +--- -# Retrieving Inventory Information - The ANTA CLI offers multiple entrypoints to access data from your local inventory. ## Inventory used of examples @@ -167,7 +168,6 @@ Options: --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. diff --git a/docs/cli/inv-from-ansible.md b/docs/cli/inv-from-ansible.md index b2672e20a..6bbaca926 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 +--- -# 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 a37af62f1..9717870ad 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 +--- -# 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 579fbdeef..6c360b7f9 100644 --- a/docs/cli/nrfu.md +++ b/docs/cli/nrfu.md @@ -1,11 +1,12 @@ +--- +anta_title: Execute Network Readiness For Use (NRFU) Testing +--- -# 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) @@ -67,6 +68,7 @@ Options: ```bash anta nrfu --device DC1-LEAF1A text ``` + ![anta nrfu text results](../imgs/anta-nrfu-text-output.png){ loading=lazy width="1600" } ## Performing NRFU with table rendering @@ -92,6 +94,7 @@ The `--group-by` option show a summarized view of the test results per host or p ```bash anta nrfu --tags LEAF table ``` + ![anta nrfu table results](../imgs/anta-nrfu-table-output.png){ loading=lazy width="1600" } For larger setups, you can also group the results by host or test to get a summarized view: @@ -99,11 +102,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 ``` + ![$1anta nrfu table group_by_host_output](../imgs/anta-nrfu-table-group-by-host-output.png){ loading=lazy width="1600" } ```bash anta nrfu table --group-by test ``` + ![$1anta nrfu table group_by_test_output](../imgs/anta-nrfu-table-group-by-test-output.png){ loading=lazy width="1600" } To get more specific information, it is possible to filter on a single device or a single test: @@ -111,11 +116,13 @@ To get more specific information, it is possible to filter on a single device or ```bash anta nrfu --device spine1 table ``` + ![$1anta nrfu table filter_host_output](../imgs/anta-nrfu-table-filter-host-output.png){ loading=lazy width="1600" } ```bash anta nrfu --test VerifyZeroTouch table ``` + ![$1anta nrfu table filter_test_output](../imgs/anta-nrfu-table-filter-test-output.png){ loading=lazy width="1600" } ## Performing NRFU with JSON rendering @@ -143,9 +150,10 @@ The `--output` option allows you to save the JSON report as a file. If specified ```bash anta nrfu --tags LEAF json ``` + ![$1anta nrfu json results](../imgs/anta-nrfu-json-output.png){ loading=lazy width="1600" } -## Performing NRFU and saving results in a CSV file. +## 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. @@ -209,6 +217,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. @@ -218,6 +227,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 ``` + ![$1anta nrfu tpl_results](../imgs/anta-nrfu-tpl-report-output.png){ loading=lazy width="1600" } The template `./custom_template.j2` is a simple Jinja2 template: diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 5f1540095..f1247b7e2 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) +--- -# 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. diff --git a/docs/cli/tag-management.md b/docs/cli/tag-management.md index 0bba29e70..9a74b7f83 100644 --- a/docs/cli/tag-management.md +++ b/docs/cli/tag-management.md @@ -3,7 +3,6 @@ ~ Use of this source code is governed by the Apache License 2.0 ~ that can be found in the LICENSE file. --> -## Overview ANTA commands can be used with a `--tags` option. This option **filters the inventory** with the specified tag(s) when running the command. @@ -112,7 +111,7 @@ anta.tests.interfaces: The following examples use the inventory and test catalog defined above. -##### No `--tags` option +#### No `--tags` option Tests without tags are run on all devices. Tests with tags will only run on devices with matching tags. @@ -140,7 +139,7 @@ Total number of selected tests: 27 └────────┴──────────────┴──────────────┴──────────────┴─────────────┴────────────────────────────────────┘ ``` -##### Single tag +#### Single tag With a tag specified, only tests matching this tag will be run on matching devices. @@ -166,7 +165,7 @@ leaf2 :: VerifyMlagStatus :: SKIPPED (MLAG is disabled) In this case, only `leaf` devices defined in the inventory are used to run tests marked with the `leaf` in the test catalog. -##### Multiple tags +#### Multiple tags It is possible to use multiple tags using the `--tags tag1,tag2` syntax. diff --git a/docs/contribution.md b/docs/contribution.md index 387e2f4c7..6299139e0 100644 --- a/docs/contribution.md +++ b/docs/contribution.md @@ -1,11 +1,12 @@ +--- +anta_title: How to contribute to ANTA +--- -# How to contribute to ANTA - Contribution model is based on a fork-model. Don't push to aristanetworks/anta directly. Always do a branch in your forked repository and create a PR. To help development, open your PR as soon as possible even in draft mode. It helps other to know on what you are working on and avoid duplicate PRs. @@ -104,14 +105,13 @@ See https://docs.pytest.org/en/7.3.x/how-to/parametrize.html#basic-pytest-genera The `DATA` structure is a list of dictionaries used to parametrize the test. The list elements have the following keys: - - `name` (str): Test name as displayed by Pytest. - - `test` (AntaTest): An AntaTest subclass imported in the test module - e.g. VerifyUptime. - - `eos_data` (list[dict]): List of data mocking EOS returned data to be passed to the test. - - `inputs` (dict): Dictionary to instantiate the `test` inputs as defined in the class from `test`. - - `expected` (dict): Expected test result structure, a dictionary containing a key +- `name` (str): Test name as displayed by Pytest. +- `test` (AntaTest): An AntaTest subclass imported in the test module - e.g. VerifyUptime. +- `eos_data` (list[dict]): List of data mocking EOS returned data to be passed to the test. +- `inputs` (dict): Dictionary to instantiate the `test` inputs as defined in the class from `test`. +- `expected` (dict): Expected test result structure, a dictionary containing a key `result` containing one of the allowed status (`Literal['success', 'failure', 'unset', 'skipped', 'error']`) and optionally a key `messages` which is a list(str) and each message is expected to be a substring of one of the actual messages in the TestResult object. - In order for your unit tests to be correctly collected, you need to import the generic test function even if not used in the Python module. Test example for `anta.tests.system.VerifyUptime` AntaTest. @@ -171,9 +171,9 @@ Run Ruff formatter.......................................................Passed Check code style with pylint.............................................Passed Checks for common misspellings in text files.............................Passed Check typing with mypy...................................................Passed +Check Markdown files style...............................................Passed ``` - ## Configure MYPYPATH In some cases, mypy can complain about not having `MYPYPATH` configured in your shell. It is especially the case when you update both an anta test and its unit test. So you can configure this environment variable with: @@ -232,4 +232,4 @@ muffet -c 2 --color=always http://127.0.0.1:8000 -e fonts.gstatic.com -b 8192 ## Continuous Integration -GitHub actions is used to test git pushes and pull requests. The workflows are defined in this [directory](https://github.com/aristanetworks/anta/tree/main/.github/workflows). We can view the results [here](https://github.com/aristanetworks/anta/actions). +GitHub actions is used to test git pushes and pull requests. The workflows are defined in this [directory](https://github.com/aristanetworks/anta/tree/main/.github/workflows). The results can be viewed [here](https://github.com/aristanetworks/anta/actions). diff --git a/docs/faq.md b/docs/faq.md index a699c8431..2d2ea6544 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -24,6 +24,7 @@ toc_depth: 2 # Frequently Asked Questions (FAQ) ## A local OS error occurred while connecting to a device + ???+ faq "A local OS error occurred while connecting to a device" When running ANTA, you can receive `A local OS error occurred while connecting to ` errors. The underlying [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) exception can have various reasons: `[Errno 24] Too many open files` or `[Errno 16] Device or resource busy`. @@ -38,13 +39,13 @@ toc_depth: 2 You can get the current hard limit for a user using the command `ulimit -n -H` while logged in. Create the file `/etc/security/limits.d/10-anta.conf` with the following content: ``` - hard nofile + hard nofile ``` The `user` is the one with which the ANTA process is started. The `value` is the new hard limit. The maximum value depends on the system. A hard limit of 16384 should be sufficient for ANTA to run in most high scale scenarios. After creating this file, log out the current session and log in again. - ## `Timeout` error in the logs + ???+ faq "`Timeout` error in the logs" When running ANTA, you can receive `Timeout` errors in the logs (could be ReadTimeout, WriteTimeout, ConnectTimeout or PoolTimeout). More details on the timeouts of the underlying library are available here: https://www.python-httpx.org/advanced/timeouts. @@ -63,8 +64,8 @@ toc_depth: 2 The timeout is increased to 50s to allow ANTA to wait for API calls a little longer. ## `ImportError` related to `urllib3` -???+ faq "`ImportError` related to `urllib3` when running ANTA" +???+ faq "`ImportError` related to `urllib3` when running ANTA" When running the `anta --help` command, some users might encounter the following error: @@ -90,9 +91,9 @@ toc_depth: 2 As per the [urllib3 v2 migration guide](https://urllib3.readthedocs.io/en/latest/v2-migration-guide.html), the root cause of this error is an incompatibility with older OpenSSL versions. For example, users on RHEL7 might consider upgrading to RHEL8, which supports the required OpenSSL version. -##`AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'` -???+ faq "`AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'` when running ANTA" +## `AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'` +???+ faq "`AttributeError: module 'lib' has no attribute 'OpenSSL_add_all_algorithms'` when running ANTA" When running the `anta` commands after installation, some users might encounter the following error: @@ -111,8 +112,8 @@ toc_depth: 2 ``` ## `__NSCFConstantString initialize` error on OSX -???+ faq "`__NSCFConstantString initialize` error on OSX" +???+ faq "`__NSCFConstantString initialize` error on OSX" This error occurs because of added security to restrict multithreading in macOS High Sierra and later versions of macOS. https://www.wefearchange.org/2018/11/forkmacos.rst.html diff --git a/docs/getting-started.md b/docs/getting-started.md index c166ebe78..aac88c640 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,8 +4,6 @@ ~ that can be found in the LICENSE file. --> -# Getting Started - This section shows how to use ANTA with basic configuration. All examples are based on Arista Test Drive (ATD) topology you can access by reaching out to your preferred SE. ## Installation @@ -257,7 +255,7 @@ $ anta nrfu \ ] ``` -You can find more information under the __usage__ section of the website +You can find more information under the **usage** section of the website ### Basic usage in a Python script diff --git a/docs/requirements-and-installation.md b/docs/requirements-and-installation.md index ebe39c482..5f99ac0ac 100644 --- a/docs/requirements-and-installation.md +++ b/docs/requirements-and-installation.md @@ -4,8 +4,6 @@ ~ that can be found in the LICENSE file. --> -# ANTA Requirements - ## Python version Python 3 (`>=3.9`) is required: @@ -21,7 +19,6 @@ This installation will deploy tests collection, scripts and all their Python req The ANTA package and the cli require some packages that are not part of the Python standard library. They are indicated in the [pyproject.toml](https://github.com/aristanetworks/anta/blob/main/pyproject.toml) file, under dependencies. - ### Install library from Pypi server ```bash @@ -36,7 +33,7 @@ pip install anta [`pipx`](https://pipx.pypa.io/stable/) is a tool to install and run python applications in isolated environments. If you plan to use ANTA only as a CLI tool you can use `pipx` to install it. `pipx` installs ANTA in an isolated python environment and makes it available globally. -``` +```bash pipx install anta[cli] ``` @@ -44,7 +41,6 @@ pipx install anta[cli] Please take the time to read through the installation instructions of `pipx` before getting started. - ### Install CLI from Pypi server Alternatively, pip install with `cli` extra is enough to install the ANTA CLI. @@ -55,7 +51,6 @@ pip install anta[cli] ### Install ANTA from github - ```bash pip install git+https://github.com/aristanetworks/anta.git pip install git+https://github.com/aristanetworks/anta.git#egg=anta[cli] diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 40fc07fa0..25b061c84 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4,8 +4,6 @@ ~ that can be found in the LICENSE file. --> -# Troubleshooting ANTA - A couple of things to check when hitting an issue with ANTA: ```mermaid @@ -26,18 +24,18 @@ flowchart LR click B "../faq" "FAQ" click E "https://github.com/aristanetworks/anta/issues" click H "https://github.com/aristanetworks/anta/issues" - style A stroke:#f00,stroke-width:2px + style A stroke:#f00,stroke-width:2px ``` ## Capturing logs -To help document the issue in Github, it is important to capture some logs so the developers can understand what is affecting your system. No logs mean that the first question asked on the issue will probably be _"Can you share some logs please?"_. +To help document the issue in Github, it is important to capture some logs so the developers can understand what is affecting your system. No logs mean that the first question asked on the issue will probably be *"Can you share some logs please?"*. ANTA provides very verbose logs when using the `DEBUG` level. When using DEBUG log level with a log file, the DEBUG logging level is not sent to stdout, but only to the file. !!! danger - On real deployments, do not use DEBUG logging level without setting a log file at the same time. + On real deployments, do not use DEBUG logging level without setting a log file at the same time. To save the logs to a file called `anta.log`, use the following flags: @@ -54,19 +52,17 @@ See `anta --help` for more information. These have to precede the `nrfu` cmd. so the `-l` and `--log-file` MUST be between `anta` and the `ANTA_COMMAND`. similarly, all the `nrfu` options MUST be set between the `nrfu` and the `ANTA_NRFU_SUBCOMMAND` (`json`, `text`, `table` or `tpl-report`). - As an example, for the `nrfu` command, it would look like: ```bash anta -l DEBUG --log-file anta.log nrfu --enable --username username --password arista --inventory inventory.yml -c nrfu.yml text ``` - ### `ANTA_DEBUG` environment variable -??? warning +!!! warning - Do not use this if you do not know why. This produces a lot of logs and can create confusion if you do not know what to look for. + Do not use this if you do not know why. This produces a lot of logs and can create confusion if you do not know what to look for. The environment variable `ANTA_DEBUG=true` enable ANTA Debug Mode. @@ -83,6 +79,7 @@ ANTA_DEBUG=true anta -l DEBUG --log-file anta.log nrfu --enable --username usern ANTA is using a specific ID in eAPI requests towards EOS. This allows for easier eAPI requests debugging on the device using EOS configuration `trace CapiApp setting UwsgiRequestContext/4,CapiUwsgiServer/4` to set up CapiApp agent logs. Then, you can view agent logs using: + ```bash bash tail -f /var/log/agents/CapiApp-* diff --git a/docs/usage-inventory-catalog.md b/docs/usage-inventory-catalog.md index d8a032f26..e180496ee 100644 --- a/docs/usage-inventory-catalog.md +++ b/docs/usage-inventory-catalog.md @@ -4,9 +4,10 @@ ~ that can be found in the LICENSE file. --> -# Inventory and Catalog +The ANTA framework needs 2 important inputs from the user to run: -The ANTA framework needs 2 important inputs from the user to run: a **device inventory** and a **test catalog**. +1. A **device inventory** +2. A **test catalog**. Both inputs can be defined in a file or programmatically. @@ -79,6 +80,7 @@ A test catalog is an instance of the [AntaCatalog](./api/catalog.md#anta.catalog In addition to the inventory file, you also have to define a catalog of tests to execute against your devices. This catalog list all your tests, their inputs and their tags. A valid test catalog file must have the following structure in either YAML or JSON: + ```yaml --- : @@ -156,6 +158,7 @@ or equivalent in JSON: ``` It is also possible to nest Python module definition: + ```yaml anta.tests: connectivity: @@ -204,7 +207,6 @@ anta.tests.system: All tests available as part of the ANTA framework are defined under the `anta.tests` Python module and are categorised per family (Python submodule). The complete list of the tests and their respective inputs is available at the [tests section](api/tests.md) of this website. - To run test to verify the EOS software version, you can do: ```yaml @@ -340,5 +342,6 @@ if __name__ == "__main__": with open(Path('anta-catalog.yml'), "w") as f: f.write(merged_catalog.dump().yaml()) ``` + !!! warning The `AntaCatalog.merge()` method is deprecated and will be removed in ANTA v2.0. Please use the `AntaCatalog.merge_catalogs()` class method instead. diff --git a/mkdocs.yml b/mkdocs.yml index e206ba218..dd417ded1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -170,7 +170,7 @@ nav: - Home: README.md - Getting Started: getting-started.md - Installation: requirements-and-installation.md - - Inventory & Tests catalog: usage-inventory-catalog.md + - Inventory and Test catalog: usage-inventory-catalog.md - ANTA CLI: - Overview: cli/overview.md - NRFU: cli/nrfu.md @@ -178,8 +178,8 @@ nav: - Inventory from CVP: cli/inv-from-cvp.md - Inventory from Ansible: cli/inv-from-ansible.md - Get Inventory Information: cli/get-inventory-information.md - - Check: cli/check.md - - Helpers: cli/debug.md + - Check commands: cli/check.md + - Debug commands: cli/debug.md - Tag Management: cli/tag-management.md - Advanced Usages: - Caching in ANTA: advanced_usages/caching.md @@ -232,6 +232,6 @@ nav: - Result Manager models: api/result_manager_models.md - Report Manager: api/report_manager.md - Runner: api/runner.md - - Troubleshooting: troubleshooting.md + - Troubleshooting ANTA: troubleshooting.md - Contributions: contribution.md - FAQ: faq.md