diff options
Diffstat (limited to 'docs')
43 files changed, 949 insertions, 287 deletions
diff --git a/docs/advanced_usages/as-python-lib.md b/docs/advanced_usages/as-python-lib.md index 49c010f..fce5e7e 100644 --- a/docs/advanced_usages/as-python-lib.md +++ b/docs/advanced_usages/as-python-lib.md @@ -6,8 +6,8 @@ ANTA is a Python library that can be used in user applications. This section describes how you can leverage ANTA Python modules to help you create your own NRFU solution. -!!! tip - If you are unfamiliar with asyncio, refer to the Python documentation relevant to your Python version - https://docs.python.org/3/library/asyncio.html +> [!TIP] +> If you are unfamiliar with asyncio, refer to the Python documentation relevant to your Python version - https://docs.python.org/3/library/asyncio.html ## [AntaDevice](../api/device.md#anta.device.AntaDevice) Abstract Class @@ -47,8 +47,10 @@ The [AntaInventory](../api/inventory.md#anta.inventory.AntaInventory) class is a --8<-- "parse_anta_inventory_file.py" ``` -!!! note "How to create your inventory file" - Please visit this [dedicated section](../usage-inventory-catalog.md) for how to use inventory and catalog files. +> [!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 diff --git a/docs/advanced_usages/custom-tests.md b/docs/advanced_usages/custom-tests.md index d79fe50..2fc61cc 100644 --- a/docs/advanced_usages/custom-tests.md +++ b/docs/advanced_usages/custom-tests.md @@ -4,8 +4,8 @@ ~ that can be found in the LICENSE file. --> -!!! info - This documentation applies for both creating tests in ANTA or creating your own test package. +> [!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. @@ -15,7 +15,7 @@ A test is a Python class where a test function is defined and will be run by the ANTA provides an abstract class [AntaTest](../api/models.md#anta.models.AntaTest). This class does the heavy lifting and provide the logic to define, collect and test data. The code below is an example of a simple test in ANTA, which is an [AntaTest](../api/models.md#anta.models.AntaTest) subclass: -```python +````python from anta.models import AntaTest, AntaCommand from anta.decorators import skip_on_platforms @@ -36,8 +36,6 @@ class VerifyTemperature(AntaTest): ``` """ - name = "VerifyTemperature" - description = "Verifies the device temperature." categories: ClassVar[list[str]] = ["hardware"] commands: ClassVar[list[AntaCommand | AntaTemplate]] = [AntaCommand(command="show system environment temperature", revision=1)] @@ -51,7 +49,7 @@ class VerifyTemperature(AntaTest): self.result.is_success() else: self.result.is_failure(f"Device temperature exceeds acceptable limits. Current system status: '{temperature_status}'") -``` +```` [AntaTest](../api/models.md#anta.models.AntaTest) also provide more advanced capabilities like [AntaCommand](../api/models.md#anta.models.AntaCommand) templating using the [AntaTemplate](../api/models.md#anta.models.AntaTemplate) class or test inputs definition and validation using [AntaTest.Input](../api/models.md#anta.models.AntaTest.Input) [pydantic](https://docs.pydantic.dev/latest/) model. This will be discussed in the sections below. @@ -61,13 +59,13 @@ Full AntaTest API documentation is available in the [API documentation section]( ### Class Attributes -- `name` (`str`): Name of the test. Used during reporting. -- `description` (`str`): A human readable description of your test. +- `name` (`str`, `optional`): Name of the test. Used during reporting. By default set to the Class name. +- `description` (`str`, `optional`): A human readable description of your test. By default set to the first line of the docstring. - `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. -!!! info - All these class attributes are mandatory. If any attribute is missing, a `NotImplementedError` exception will be raised during class instantiation. +> [!INFO] +> All these class attributes are mandatory. If any attribute is missing, a `NotImplementedError` exception will be raised during class instantiation. ### Instance Attributes @@ -84,11 +82,15 @@ 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. - -!!! note "AntaDevice object" - Even if `device` is not a private attribute, you should not need to access this object in your code. +> [!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. +> +> - **AntaDevice object** +> +> Even if `device` is not a private attribute, you should not need to access this object in your code. ### Test Inputs @@ -131,8 +133,8 @@ Full `ResultOverwrite` model documentation is available in [API documentation se show_root_toc_entry: false heading_level: 10 -!!! note - The pydantic model is configured using the [`extra=forbid`](https://docs.pydantic.dev/latest/usage/model_config/#extra-attributes) that will fail input validation if extra fields are provided. +> [!NOTE] +> The pydantic model is configured using the [`extra=forbid`](https://docs.pydantic.dev/latest/usage/model_config/#extra-attributes) that will fail input validation if extra fields are provided. ### Methods @@ -162,8 +164,8 @@ In this section, we will go into all the details of writing an [AntaTest](../api Import [anta.models.AntaTest](../api/models.md#anta.models.AntaTest) and define your own class. Define the mandatory class attributes using [anta.models.AntaCommand](../api/models.md#anta.models.AntaCommand), [anta.models.AntaTemplate](../api/models.md#anta.models.AntaTemplate) or both. -!!! info - Caching can be disabled per `AntaCommand` or `AntaTemplate` by setting the `use_cache` argument to `False`. For more details about how caching is implemented in ANTA, please refer to [Caching in ANTA](../advanced_usages/caching.md). +> [!NOTE] +> Caching can be disabled per `AntaCommand` or `AntaTemplate` by setting the `use_cache` argument to `False`. For more details about how caching is implemented in ANTA, please refer to [Caching in ANTA](../advanced_usages/caching.md). ```python from anta.models import AntaTest, AntaCommand, AntaTemplate @@ -171,11 +173,11 @@ from anta.models import AntaTest, AntaCommand, AntaTemplate class <YourTestName>(AntaTest): """ - <a docstring description of your test> + <a docstring description of your test, the first line is used as description of the test by default> """ - name = "YourTestName" # should be your class name - description = "<test description in human reading format>" + # name = <override> # uncomment to override default behavior of name=Class Name + # description = <override> # uncomment to override default behavior of description=first line of docstring categories = ["<arbitrary category>", "<another arbitrary category>"] commands = [ AntaCommand( @@ -195,21 +197,23 @@ class <YourTestName>(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) - * 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. - - For instance, the `VerifyBFDPeersHealth` test leverages the first revision of `show bfd peers`: - - ``` - # revision 1 as later revision introduce additional nesting for type - commands = [AntaCommand(command="show bfd peers", revision=1)] - ``` +> [!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) +> - 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. +> +> For instance, the `VerifyBFDPeersHealth` test leverages the first revision of `show bfd peers`: +> +> ```python +> # revision 1 as later revision introduce additional nesting for type +> commands = [AntaCommand(command="show bfd peers", revision=1)] +> ``` ### Inputs definition @@ -244,8 +248,8 @@ You can also leverage [anta.custom_types](../api/types.md) that provides reusabl Regarding required, optional and nullable fields, refer to this [documentation](https://docs.pydantic.dev/latest/migration/#required-optional-and-nullable-fields) on how to define them. -!!! note - All the `pydantic` features are supported. For instance you can define [validators](https://docs.pydantic.dev/latest/usage/validators/) for complex input validation. +> [!NOTE] +> All the `pydantic` features are supported. For instance you can define [validators](https://docs.pydantic.dev/latest/usage/validators/) for complex input validation. ### Template rendering @@ -340,10 +344,10 @@ class VerifyTemperature(AntaTest): ## Access your custom tests in the test catalog -!!! warning "" - This section is required only if you are not merging your development into ANTA. Otherwise, just follow [contribution guide](../contribution.md). +> [!WARNING] +> This section is required only if you are not merging your development into ANTA. Otherwise, just follow [contribution guide](../contribution.md). -For that, you need to create your own Python package as described in this [hitchhiker's guide](https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/) to package Python code. We assume it is well known and we won't focus on this aspect. Thus, your package must be impartable by ANTA hence available in the module search path `sys.path` (you can use `PYTHONPATH` for example). +For that, you need to create your own Python package as described in this [hitchhiker's guide](https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/) to package Python code. We assume it is well known and we won't focus on this aspect. Thus, your package must be importable by ANTA hence available in the module search path `sys.path` (you can use `PYTHONPATH` for example). It is very similar to what is documented in [catalog section](../usage-inventory-catalog.md) but you have to use your own package name.2 diff --git a/docs/api/tests.avt.md b/docs/api/tests.avt.md index f9e1acf..a55fcce 100644 --- a/docs/api/tests.avt.md +++ b/docs/api/tests.avt.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for Adaptive Virtual Topology (AVT) tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.avt + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,18 @@ anta_title: ANTA catalog for Adaptive Virtual Topology (AVT) tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.avt + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + anta_hide_test_module_description: true + merge_init_into_class: false + show_labels: true + filters: + - "!^__init__" + - "!^__str__" diff --git a/docs/api/tests.bfd.md b/docs/api/tests.bfd.md index 719466e..ee95087 100644 --- a/docs/api/tests.bfd.md +++ b/docs/api/tests.bfd.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for BFD tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.bfd + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,16 @@ anta_title: ANTA catalog for BFD tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.bfd + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: ["!^__str__"] diff --git a/docs/api/tests.connectivity.md b/docs/api/tests.connectivity.md index 0dd5d44..439cec8 100644 --- a/docs/api/tests.connectivity.md +++ b/docs/api/tests.connectivity.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for connectivity tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.connectivity + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,16 @@ anta_title: ANTA catalog for connectivity tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.connectivity + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: ["!^__str__"] diff --git a/docs/api/tests.cvx.md b/docs/api/tests.cvx.md new file mode 100644 index 0000000..c9ff53d --- /dev/null +++ b/docs/api/tests.cvx.md @@ -0,0 +1,20 @@ +--- +anta_title: ANTA catalog for CVX tests +--- +<!-- + ~ 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.tests.cvx + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: + - "!test" + - "!render" diff --git a/docs/api/tests.interfaces.md b/docs/api/tests.interfaces.md index 95630f5..3d863ee 100644 --- a/docs/api/tests.interfaces.md +++ b/docs/api/tests.interfaces.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for interfaces tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.interfaces + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,16 @@ anta_title: ANTA catalog for interfaces tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.interfaces + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: ["!^__str__"] diff --git a/docs/api/tests.md b/docs/api/tests.md index 7dd74c1..a36c9eb 100644 --- a/docs/api/tests.md +++ b/docs/api/tests.md @@ -18,6 +18,7 @@ Here are the tests that we currently provide: - [BFD](tests.bfd.md) - [Configuration](tests.configuration.md) - [Connectivity](tests.connectivity.md) +- [CVX](tests.cvx.md) - [Field Notices](tests.field_notices.md) - [Flow Tracking](tests.flow_tracking.md) - [GreenT](tests.greent.md) @@ -44,6 +45,10 @@ Here are the tests that we currently provide: - [VLAN](tests.vlan.md) - [VXLAN](tests.vxlan.md) +!!! tip + + You can use `anta get tests` from the CLI to list all the tests available with an example. Refer to [documentation](../cli/get-tests.md) for more options. + ## Using the Tests All these tests can be imported in a [catalog](../usage-inventory-catalog.md) to be used by [the ANTA CLI](../cli/nrfu.md) or in your [own framework](../advanced_usages/as-python-lib.md). diff --git a/docs/api/tests.routing.bgp.md b/docs/api/tests.routing.bgp.md index 4537ec2..b40ff7b 100644 --- a/docs/api/tests.routing.bgp.md +++ b/docs/api/tests.routing.bgp.md @@ -7,7 +7,13 @@ anta_title: ANTA catalog for BGP tests ~ that can be found in the LICENSE file. --> +!!! info "`multi-agent` Service Routing Protocols Model Requirements" + The BGP tests in this section are only supported on switches running the `multi-agent` routing protocols model. Starting from EOS version 4.30.1F, `service routing protocols model` is set to `multi-agent` by default. These BGP commands may **not** be compatible with switches running the legacy `ribd` routing protocols model and may fail if attempted. + +# Tests + ::: anta.tests.routing.bgp + options: show_root_heading: false show_root_toc_entry: false @@ -19,3 +25,21 @@ anta_title: ANTA catalog for BGP tests - "!test" - "!render" - "!^_[^_]" + +# Input models + +::: anta.input_models.routing.bgp + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + anta_hide_test_module_description: true + merge_init_into_class: false + show_labels: true + filters: + - "!^__init__" + - "!^__str__" + - "!AFI_SAFI_EOS_KEY" + - "!eos_key" + - "!BgpAfi" diff --git a/docs/api/tests.routing.generic.md b/docs/api/tests.routing.generic.md index 1c4c39d..bbc8904 100644 --- a/docs/api/tests.routing.generic.md +++ b/docs/api/tests.routing.generic.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for generic routing tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.routing.generic + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,16 @@ anta_title: ANTA catalog for generic routing tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.routing.generic + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: ["!^__str__"] diff --git a/docs/api/tests.routing.isis.md b/docs/api/tests.routing.isis.md index bf50c72..16ca7ff 100644 --- a/docs/api/tests.routing.isis.md +++ b/docs/api/tests.routing.isis.md @@ -8,6 +8,7 @@ anta_title: ANTA catalog for IS-IS tests --> ::: anta.tests.routing.isis + options: show_root_heading: false show_root_toc_entry: false diff --git a/docs/api/tests.routing.ospf.md b/docs/api/tests.routing.ospf.md index 2fd0cd4..12bb3ec 100644 --- a/docs/api/tests.routing.ospf.md +++ b/docs/api/tests.routing.ospf.md @@ -8,6 +8,7 @@ anta_title: ANTA catalog for OSPF tests --> ::: anta.tests.routing.ospf + options: show_root_heading: false show_root_toc_entry: false diff --git a/docs/api/tests.security.md b/docs/api/tests.security.md index fe008ba..5997832 100644 --- a/docs/api/tests.security.md +++ b/docs/api/tests.security.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for security tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.security + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,18 @@ anta_title: ANTA catalog for security tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.security + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: + - "!^__init__" + - "!^__str__" diff --git a/docs/api/tests.services.md b/docs/api/tests.services.md index 63d9234..cd37148 100644 --- a/docs/api/tests.services.md +++ b/docs/api/tests.services.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for services tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.services + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,16 @@ anta_title: ANTA catalog for services tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.services + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: ["!^__str__"] diff --git a/docs/api/tests.stun.md b/docs/api/tests.stun.md index b4274e9..6a73b88 100644 --- a/docs/api/tests.stun.md +++ b/docs/api/tests.stun.md @@ -7,6 +7,8 @@ anta_title: ANTA catalog for STUN tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.stun options: show_root_heading: false @@ -18,3 +20,18 @@ anta_title: ANTA catalog for STUN tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.stun + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: + - "!^__init__" + - "!^__str__" diff --git a/docs/api/tests.system.md b/docs/api/tests.system.md index 5dcfbc0..26568e2 100644 --- a/docs/api/tests.system.md +++ b/docs/api/tests.system.md @@ -7,7 +7,10 @@ anta_title: ANTA catalog for System tests ~ that can be found in the LICENSE file. --> +# Tests + ::: anta.tests.system + options: show_root_heading: false show_root_toc_entry: false @@ -18,3 +21,16 @@ anta_title: ANTA catalog for System tests filters: - "!test" - "!render" + +# Input models + +::: anta.input_models.system + + options: + show_root_heading: false + show_root_toc_entry: false + show_bases: false + merge_init_into_class: false + anta_hide_test_module_description: true + show_labels: true + filters: ["!^__str__"] diff --git a/docs/cli/debug.md b/docs/cli/debug.md index 4c864db..45ad791 100644 --- a/docs/cli/debug.md +++ b/docs/cli/debug.md @@ -61,6 +61,7 @@ Options: --help Show this message and exit. ``` +> [!TIP] > `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices ### Example @@ -162,8 +163,8 @@ Run templated command 'show vlan {vlan_id}' with {'vlan_id': '10'} on DC1-LEAF1A ### 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. +> [!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 diff --git a/docs/cli/exec.md b/docs/cli/exec.md index 2eb12ee..a7a0fe3 100644 --- a/docs/cli/exec.md +++ b/docs/cli/exec.md @@ -64,6 +64,7 @@ Options: --help Show this message and exit. ``` +> [!TIP] > `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices ### Example @@ -235,12 +236,14 @@ Options: 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. + --configure [DEPRECATED] 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. ``` +> [!TIP] > `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. @@ -248,13 +251,18 @@ When executed, this command fetches tech-support files and downloads them locall 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. + +> [!CAUTION] +> **Deprecation** +> +> ANTA can automatically configure `aaa authorization exec default local` using the `anta exec collect-tech-support --configure` option but this option is deprecated and will be removed in ANTA 2.0.0. + 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. +> [!WARNING] +> By default **all** the tech-support files present on the devices are retrieved. ### Example diff --git a/docs/cli/get-inventory-information.md b/docs/cli/get-inventory-information.md index ab1bebc..d45cb6a 100644 --- a/docs/cli/get-inventory-information.md +++ b/docs/cli/get-inventory-information.md @@ -52,8 +52,8 @@ Options: --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. +> [!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 diff --git a/docs/cli/get-tests.md b/docs/cli/get-tests.md new file mode 100644 index 0000000..3c2b369 --- /dev/null +++ b/docs/cli/get-tests.md @@ -0,0 +1,120 @@ +--- +anta_title: Retrieving Tests 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. + --> + +`anta get tests` commands help you discover available tests in ANTA. + +### Command overview + +```bash +Usage: anta get tests [OPTIONS] + + Show all builtin ANTA tests with an example output retrieved from each test + documentation. + +Options: + --module TEXT Filter tests by module name. [default: anta.tests] + --test TEXT Filter by specific test name. If module is specified, + searches only within that module. + --short Display test names without their inputs. + --count Print only the number of tests found. + --help Show this message and exit. +``` + +> [!TIP] +> By default, `anta get tests` will retrieve all tests available in ANTA. + +### Examples + +#### Default usage + +``` yaml title="anta get tests" +anta.tests.aaa: + - VerifyAcctConsoleMethods: + # Verifies the AAA accounting console method lists for different accounting types (system, exec, commands, dot1x). + methods: + - local + - none + - logging + types: + - system + - exec + - commands + - dot1x + - VerifyAcctDefaultMethods: + # Verifies the AAA accounting default method lists for different accounting types (system, exec, commands, dot1x). + methods: + - local + - none + - logging + types: + - system + - exec + - commands + - dot1x +[...] +``` + +#### Module usage + +To retrieve all the tests from `anta.tests.stun`. + +``` yaml title="anta get tests --module anta.tests.stun" +anta.tests.stun: + - VerifyStunClient: + # Verifies STUN client settings, including local IP/port and optionally public IP/port. + stun_clients: + - source_address: 172.18.3.2 + public_address: 172.18.3.21 + source_port: 4500 + public_port: 6006 + - source_address: 100.64.3.2 + public_address: 100.64.3.21 + source_port: 4500 + public_port: 6006 + - VerifyStunServer: + # Verifies the STUN server status is enabled and running. +``` + +#### Test usage + +``` yaml title="anta get tests --test VerifyTacacsSourceIntf" +anta.tests.aaa: + - VerifyTacacsSourceIntf: + # Verifies TACACS source-interface for a specified VRF. + intf: Management0 + vrf: MGMT +``` + +> [!TIP] +> You can filter tests by providing a prefix - ANTA will return all tests that start with your specified string. + +```yaml title="anta get tests --test VerifyTacacs" +anta.tests.aaa: + - VerifyTacacsServerGroups: + # Verifies if the provided TACACS server group(s) are configured. + groups: + - TACACS-GROUP1 + - TACACS-GROUP2 + - VerifyTacacsServers: + # Verifies TACACS servers are configured for a specified VRF. + servers: + - 10.10.10.21 + - 10.10.10.22 + vrf: MGMT + - VerifyTacacsSourceIntf: + # Verifies TACACS source-interface for a specified VRF. + intf: Management0 + vrf: MGMT +``` + +#### Count the tests + +```bash title="anta get tests --count" +There are 155 tests available in `anta.tests`. +``` diff --git a/docs/cli/inv-from-ansible.md b/docs/cli/inv-from-ansible.md index 6bbaca9..c891693 100644 --- a/docs/cli/inv-from-ansible.md +++ b/docs/cli/inv-from-ansible.md @@ -31,26 +31,13 @@ Options: --help Show this message and exit. ``` -!!! 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." - -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 inheritance when using the `--ansible-group` option. +> [!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." +> +> - The current implementation only considers devices directly attached to a specific Ansible group and does not support inheritance 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 @@ -60,7 +47,7 @@ By default, if user does not provide `--output` file, anta will save output to c ```yaml --- -tooling: +all: children: endpoints: hosts: @@ -80,3 +67,16 @@ tooling: ansible_host: 10.73.252.43 type: endpoint ``` + +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 +``` diff --git a/docs/cli/inv-from-cvp.md b/docs/cli/inv-from-cvp.md index 9717870..e08ffd6 100644 --- a/docs/cli/inv-from-cvp.md +++ b/docs/cli/inv-from-cvp.md @@ -52,8 +52,8 @@ anta_inventory: - pod2 ``` -!!! warning - The current implementation only considers devices directly attached to a specific container when using the `--cvp-container` option. +> [!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 diff --git a/docs/cli/nrfu.md b/docs/cli/nrfu.md index 0f2b425..667eb5f 100644 --- a/docs/cli/nrfu.md +++ b/docs/cli/nrfu.md @@ -26,8 +26,8 @@ ANTA provides a set of commands for performing NRFU tests on devices. These comm 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. +> [!TIP] +> Issuing the command `anta nrfu` will run `anta nrfu table` without any option. ### Tag management diff --git a/docs/cli/overview.md b/docs/cli/overview.md index f1247b7..be6b1f4 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -45,9 +45,10 @@ Then, run the CLI without options: anta nrfu ``` -!!! note - All environment variables may not be needed for every commands. - Refer to `<command> --help` for the comprehensive environment variables names. +> [!NOTE] +> All environment variables may not be needed for every commands. +> +> Refer to `<command> --help` for the comprehensive environment variables names. Below are the environment variables usable with the `anta nrfu` command: @@ -63,8 +64,8 @@ Below are the environment variables usable with the `anta nrfu` command: | 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). +> [!NOTE] +> 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 diff --git a/docs/cli/tag-management.md b/docs/cli/tag-management.md index ad5ccf3..b07e0c9 100644 --- a/docs/cli/tag-management.md +++ b/docs/cli/tag-management.md @@ -4,9 +4,7 @@ ~ that can be found in the LICENSE file. --> -ANTA commands can be used with a `--tags` option. This option **filters the inventory** with the specified tag(s) when running the command. - -Tags can also be used to **restrict a specific test** to a set of devices when using `anta nrfu`. +ANTA uses tags to define test-to-device mappings (tests run on devices with matching tags) and the `--tags` CLI option acts as a filter to execute specific test/device combinations. ## Defining tags @@ -94,10 +92,11 @@ anta.tests.interfaces: 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. +> [!TIP] +> +> - A tag used to filter a test can also be a device name +> +> - **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 diff --git a/docs/contribution.md b/docs/contribution.md index 88f09c1..50aed44 100644 --- a/docs/contribution.md +++ b/docs/contribution.md @@ -29,7 +29,7 @@ $ pip install -e .[dev,cli] $ pip list -e Package Version Editable project location ------- ------- ------------------------- -anta 1.1.0 /mnt/lab/projects/anta +anta 1.2.0 /mnt/lab/projects/anta ``` Then, [`tox`](https://tox.wiki/) is configured with few environments to run CI locally: @@ -86,9 +86,9 @@ Success: no issues found in 82 source files > NOTE: Typing is configured quite strictly, do not hesitate to reach out if you have any questions, struggles, nightmares. -## Unit tests +## Unit tests with Pytest -To keep high quality code, we require to provide a Pytest for every tests implemented in ANTA. +To keep high quality code, we require to provide a **Pytest** for every tests implemented in ANTA. All submodule should have its own pytest section under `tests/units/anta_tests/<submodule-name>.py`. diff --git a/docs/faq.md b/docs/faq.md index 7a58663..ee823b4 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -110,6 +110,17 @@ anta_title: Frequently Asked Questions (FAQ) pip install -U pyopenssl>22.0 ``` +## Caveat running on non-POSIX platforms (e.g. Windows) + +???+ faq "Caveat running on non-POSIX platforms (e.g. Windows)" + + While ANTA should in general work on non-POSIX platforms (e.g. Windows), + there are some known limitations: + + - On non-Posix platforms, ANTA is not able to check and/or adjust the system limit of file descriptors. + + ANTA test suite is being run in the CI on a Windows runner. + ## `__NSCFConstantString initialize` error on OSX ???+ faq "`__NSCFConstantString initialize` error on OSX" @@ -124,6 +135,40 @@ anta_title: Frequently Asked Questions (FAQ) export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ``` +## EOS AAA configuration for an ANTA-only user + +???+ faq "EOS AAA configuration for an ANTA-only user" + + Here is a starting guide to configure an ANTA-only user to run ANTA tests on a device. + + !!! warning + + This example is not using TACACS / RADIUS but only local AAA + + 1. Configure the following role. + + ```bash + role anta-users + 10 permit command show + 20 deny command .* + ``` + + You can then add other commands if they are required for your test catalog (`ping` for example) and then tighten down the show commands to only those required for your tests. + + 2. Configure the following authorization (You may need to adapt depending on your AAA setup). + + ```bash + aaa authorization commands all default local + ``` + + 3. Configure a user for the role. + + ```bash + user anta role anta-users secret <secret> + ``` + + 4. You can then use the credentials `anta` / `<secret>` to run ANTA against the device and adjust the role as required. + # Still facing issues? If you've tried the above solutions and continue to experience problems, please follow the [troubleshooting](troubleshooting.md) instructions and report the issue in our [GitHub repository](https://github.com/aristanetworks/anta). diff --git a/docs/getting-started.md b/docs/getting-started.md index aac88c6..bcd5a2c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -48,26 +48,7 @@ management api http-commands ANTA uses an inventory to list the target devices for the tests. You can create a file manually with this format: ```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'] +--8<-- "getting-started/inventory.yml" ``` > You can read more details about how to build your inventory [here](usage-inventory-catalog.md#device-inventory) @@ -90,31 +71,7 @@ The structure to follow is like: Here is an example for basic tests: ```yaml -# Load anta.tests.software -anta.tests.software: - - VerifyEOSVersion: # Verifies the device is running one of the allowed EOS version. - versions: # List of allowed EOS versions. - - 4.25.4M - - 4.26.1F - - '4.28.3M-28837868.4283M (engineering build)' - - VerifyTerminAttrVersion: - versions: - - v1.22.1 - -anta.tests.system: - - VerifyUptime: # Verifies the device uptime is higher than a value. - minimum: 1 - - VerifyNTP: - - VerifySyslog: - -anta.tests.mlag: - - VerifyMlagStatus: - - VerifyMlagInterfaces: - - VerifyMlagConfigSanity: - -anta.tests.configuration: - - VerifyZeroTouch: # Verifies ZeroTouch is disabled. - - VerifyRunningConfigDiffs: +--8<-- "getting-started/catalog.yml" ``` ## Test your network @@ -135,128 +92,32 @@ This entrypoint has multiple options to manage test coverage and reporting. To run the NRFU, you need to select an output format amongst ["json", "table", "text", "tpl-report"]. For a first usage, `table` is recommended. By default all test results for all devices are rendered but it can be changed to a report per test case or per host +!!! Note + The following examples shows how to pass all the CLI options. + + See how to use environment variables instead in the [CLI overview](cli/overview.md#anta-environment-variables) + #### Default report using table ```bash -anta nrfu \ - --username tom \ - --password arista123 \ - --enable \ - --enable-password t \ - --inventory .personal/inventory_atd.yml \ - --catalog .personal/tests-bases.yml \ - table --tags leaf - - -╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ -╰──────────────────────────────────────────────────────╯ -[10:17:24] INFO Running ANTA tests... runner.py:75 - • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40/40 • 0:00:02 • 0:00:00 - - All tests results -┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ -┃ Device IP ┃ Test Name ┃ Test Status ┃ Message(s) ┃ Test description ┃ Test category ┃ -┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ -│ leaf01 │ VerifyEOSVersion │ success │ │ Verifies the device is running one of the allowed EOS version. │ software │ -│ leaf01 │ VerifyTerminAttrVersion │ success │ │ Verifies the device is running one of the allowed TerminAttr │ software │ -│ │ │ │ │ version. │ │ -│ leaf01 │ VerifyUptime │ success │ │ Verifies the device uptime is higher than a value. │ system │ -│ leaf01 │ VerifyNTP │ success │ │ Verifies NTP is synchronised. │ system │ -│ leaf01 │ VerifySyslog │ success │ │ Verifies the device had no syslog message with a severity of warning │ system │ -│ │ │ │ │ (or a more severe message) during the last 7 days. │ │ -│ leaf01 │ VerifyMlagStatus │ skipped │ MLAG is disabled │ This test verifies the health status of the MLAG configuration. │ mlag │ -│ leaf01 │ VerifyMlagInterfaces │ skipped │ MLAG is disabled │ This test verifies there are no inactive or active-partial MLAG │ mlag │ -[...] -│ leaf04 │ VerifyMlagConfigSanity │ skipped │ MLAG is disabled │ This test verifies there are no MLAG config-sanity inconsistencies. │ mlag │ -│ leaf04 │ VerifyZeroTouch │ success │ │ Verifies ZeroTouch is disabled. │ configuration │ -│ leaf04 │ VerifyRunningConfigDiffs │ success │ │ │ configuration │ -└───────────┴──────────────────────────┴─────────────┴──────────────────┴──────────────────────────────────────────────────────────────────────┴───────────────┘ +--8<-- "getting-started/anta_nrfu_table.sh" +--8<-- "getting-started/anta_nrfu_table.output" ``` #### Report in text mode ```bash -$ anta nrfu \ - --username tom \ - --password arista123 \ - --enable \ - --enable-password t \ - --inventory .personal/inventory_atd.yml \ - --catalog .personal/tests-bases.yml \ - text --tags leaf - -╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ -╰──────────────────────────────────────────────────────╯ -[10:20:47] INFO Running ANTA tests... runner.py:75 - • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40/40 • 0:00:01 • 0:00:00 -leaf01 :: VerifyEOSVersion :: SUCCESS -leaf01 :: VerifyTerminAttrVersion :: SUCCESS -leaf01 :: VerifyUptime :: SUCCESS -leaf01 :: VerifyNTP :: SUCCESS -leaf01 :: VerifySyslog :: SUCCESS -leaf01 :: VerifyMlagStatus :: SKIPPED (MLAG is disabled) -leaf01 :: VerifyMlagInterfaces :: SKIPPED (MLAG is disabled) -leaf01 :: VerifyMlagConfigSanity :: SKIPPED (MLAG is disabled) -[...] +--8<-- "getting-started/anta_nrfu_text.sh" +--8<-- "getting-started/anta_nrfu_text.output" ``` #### Report in JSON format ```bash -$ anta nrfu \ - --username tom \ - --password arista123 \ - --enable \ - --enable-password t \ - --inventory .personal/inventory_atd.yml \ - --catalog .personal/tests-bases.yml \ - json --tags leaf - -╭────────────────────── Settings ──────────────────────╮ -│ Running ANTA tests: │ -│ - ANTA Inventory contains 6 devices (AsyncEOSDevice) │ -│ - Tests catalog contains 10 tests │ -╰──────────────────────────────────────────────────────╯ -[10:21:51] INFO Running ANTA tests... runner.py:75 - • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40/40 • 0:00:02 • 0:00:00 -╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ -│ JSON results of all tests │ -╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ -[ - { - "name": "leaf01", - "test": "VerifyEOSVersion", - "categories": [ - "software" - ], - "description": "Verifies the device is running one of the allowed EOS version.", - "result": "success", - "messages": [], - "custom_field": "None", - }, - { - "name": "leaf01", - "test": "VerifyTerminAttrVersion", - "categories": [ - "software" - ], - "description": "Verifies the device is running one of the allowed TerminAttr version.", - "result": "success", - "messages": [], - "custom_field": "None", - }, -[...] -] +--8<-- "getting-started/anta_nrfu_json.sh" +--8<-- "getting-started/anta_nrfu_json.output" ``` -You can find more information under the **usage** section of the website - ### Basic usage in a Python script ```python diff --git a/docs/requirements-and-installation.md b/docs/requirements-and-installation.md index 1b35758..e9fbbc7 100644 --- a/docs/requirements-and-installation.md +++ b/docs/requirements-and-installation.md @@ -25,9 +25,8 @@ The ANTA package and the cli require some packages that are not part of the Pyth pip install anta ``` -!!! Warning - - * This command alone **will not** install the ANTA CLI requirements. +> [!WARNING] +> This command alone **will not** install the ANTA CLI requirements. ### Install ANTA CLI as an application with `pipx` @@ -37,9 +36,8 @@ pip install anta pipx install anta[cli] ``` -!!! Info - - Please take the time to read through the installation instructions of `pipx` before getting started. +> [!INFO] +> Please take the time to read through the installation instructions of `pipx` before getting started. ### Install CLI from Pypi server @@ -80,13 +78,13 @@ which anta /home/tom/.pyenv/shims/anta ``` -!!! warning - Before running the `anta --version` command, please be aware that some users have reported issues related to the `urllib3` package. If you encounter an error at this step, please refer to our [FAQ](faq.md) page for guidance on resolving it. +> [!WARNING] +> Before running the `anta --version` command, please be aware that some users have reported issues related to the `urllib3` package. If you encounter an error at this step, please refer to our [FAQ](faq.md) page for guidance on resolving it. ```bash # Check ANTA version anta --version -anta, version v1.1.0 +anta, version v1.2.0 ``` ## EOS Requirements diff --git a/docs/scripts/generate_examples_tests.py b/docs/scripts/generate_examples_tests.py new file mode 100755 index 0000000..a88d9d6 --- /dev/null +++ b/docs/scripts/generate_examples_tests.py @@ -0,0 +1,29 @@ +#!/usr/bin/env python +# Copyright (c) 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. +"""Generates examples/tests.py.""" + +import os +from contextlib import redirect_stdout +from pathlib import Path +from sys import path + +# Override global path to load anta from pwd instead of any installed version. +path.insert(0, str(Path(__file__).parents[2])) + +examples_tests_path = Path(__file__).parents[2] / "examples" / "tests.yaml" + + +prev = os.environ.get("TERM", "") +os.environ["TERM"] = "dumb" +# imported after TERM is set to act upon rich console. +from anta.cli.get.commands import tests # noqa: E402 + +with examples_tests_path.open("w") as f: + f.write("---\n") + with redirect_stdout(f): + # removing the style + tests() + +os.environ["TERM"] = prev diff --git a/docs/scripts/generate_svg.py b/docs/scripts/generate_svg.py index f017b24..2eca6ac 100644 --- a/docs/scripts/generate_svg.py +++ b/docs/scripts/generate_svg.py @@ -94,7 +94,7 @@ if __name__ == "__main__": # Redirect stdout of the program towards another StringIO to capture help # that is not part or anta rich console # redirect potential progress bar output to console by patching - with patch("anta.cli.nrfu.anta_progress_bar", custom_progress_bar), suppress(SystemExit): + with patch("anta.cli.nrfu.utils.anta_progress_bar", custom_progress_bar), suppress(SystemExit): function() if "--help" in args: diff --git a/docs/snippets/getting-started/anta_nrfu_json.output b/docs/snippets/getting-started/anta_nrfu_json.output new file mode 100644 index 0000000..c6db49d --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_json.output @@ -0,0 +1,54 @@ +╭────────────────────── Settings ──────────────────────╮ +│ - ANTA Inventory contains 5 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 9 tests │ +╰──────────────────────────────────────────────────────╯ + +[10:53:11] INFO Preparing ANTA NRFU Run ... tools.py:294 + INFO Connecting to devices ... tools.py:294 + INFO Connecting to devices completed in: 0:00:00.053. tools.py:302 + INFO Preparing the tests ... tools.py:294 + INFO Preparing the tests completed in: 0:00:00.001. tools.py:302 + INFO --- ANTA NRFU Run Information --- runner.py:276 + Number of devices: 5 (5 established) + Total number of selected tests: 45 + Maximum number of open file descriptors for the current ANTA process: 16384 + --------------------------------- + INFO Preparing ANTA NRFU Run completed in: 0:00:00.065. tools.py:302 + INFO Running ANTA tests ... tools.py:294 +[10:53:12] INFO Running ANTA tests completed in: 0:00:00.857. tools.py:302 + INFO Cache statistics for 's1-spine1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-spine2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf3': 1 hits / 9 command(s) (11.11%) runner.py:75 + • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45/45 • 0:00:00 • 0:00:00 + +╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ +│ JSON results │ +╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ +[ + { + "name": "s1-spine1", + "test": "VerifyNTP", + "categories": [ + "system" + ], + "description": "Verifies if NTP is synchronised.", + "result": "success", + "messages": [], + "custom_field": null + }, + { + "name": "s1-spine1", + "test": "VerifyMlagConfigSanity", + "categories": [ + "mlag" + ], + "description": "Verifies there are no MLAG config-sanity inconsistencies.", + "result": "skipped", + "messages": [ + "MLAG is disabled" + ], + "custom_field": null + }, + [...] diff --git a/docs/snippets/getting-started/anta_nrfu_json.sh b/docs/snippets/getting-started/anta_nrfu_json.sh new file mode 100644 index 0000000..932aeb3 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_json.sh @@ -0,0 +1,9 @@ +anta nrfu \ + --username arista \ + --password arista \ + --inventory ./inventory.yml \ + `# uncomment the next two lines if you have an enable password `\ + `# --enable `\ + `# --enable-password <password> `\ + --catalog ./catalog.yml \ + json diff --git a/docs/snippets/getting-started/anta_nrfu_table.output b/docs/snippets/getting-started/anta_nrfu_table.output new file mode 100644 index 0000000..a34b5bd --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_table.output @@ -0,0 +1,47 @@ +╭────────────────────── Settings ──────────────────────╮ +│ - ANTA Inventory contains 5 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 9 tests │ +╰──────────────────────────────────────────────────────╯ + +[10:53:01] INFO Preparing ANTA NRFU Run ... tools.py:294 + INFO Connecting to devices ... tools.py:294 + INFO Connecting to devices completed in: 0:00:00.058. tools.py:302 + INFO Preparing the tests ... tools.py:294 + INFO Preparing the tests completed in: 0:00:00.001. tools.py:302 + INFO --- ANTA NRFU Run Information --- runner.py:276 + Number of devices: 5 (5 established) + Total number of selected tests: 45 + Maximum number of open file descriptors for the current ANTA process: 16384 + --------------------------------- + INFO Preparing ANTA NRFU Run completed in: 0:00:00.069. tools.py:302 + INFO Running ANTA tests ... tools.py:294 +[10:53:02] INFO Running ANTA tests completed in: 0:00:00.969. tools.py:302 + INFO Cache statistics for 's1-spine1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-spine2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf3': 1 hits / 9 command(s) (11.11%) runner.py:75 + • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45/45 • 0:00:00 • 0:00:00 + + All tests results +┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓ +┃ Device ┃ Test Name ┃ Test Status ┃ Message(s) ┃ Test description ┃ Test category ┃ +┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩ +│ s1-spine1 │ VerifyMlagConfigSanity │ skipped │ MLAG is disabled │ Verifies there are no MLAG config-sanity │ MLAG │ +│ │ │ │ │ inconsistencies. │ │ +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +│ s1-spine1 │ VerifyEOSVersion │ failure │ device is running version │ Verifies the EOS version of the device. │ Software │ +│ │ │ │ "4.32.2F-38195967.4322F (engineering │ │ │ +│ │ │ │ build)" not in expected versions: │ │ │ +│ │ │ │ ['4.25.4M', '4.26.1F', │ │ │ +│ │ │ │ '4.28.3M-28837868.4283M (engineering │ │ │ +│ │ │ │ build)'] │ │ │ +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +[...] +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +│ s1-leaf3 │ VerifyTerminAttrVersion │ failure │ device is running TerminAttr version │ Verifies the TerminAttr version of the │ Software │ +│ │ │ │ v1.34.0 and is not in the allowed list: │ device. │ │ +│ │ │ │ ['v1.22.1'] │ │ │ +├───────────┼──────────────────────────┼─────────────┼────────────────────────────────────────────┼────────────────────────────────────────────┼───────────────┤ +│ s1-leaf3 │ VerifyZeroTouch │ success │ │ Verifies ZeroTouch is disabled │ Configuration │ +└───────────┴──────────────────────────┴─────────────┴────────────────────────────────────────────┴────────────────────────────────────────────┴───────────────┘ diff --git a/docs/snippets/getting-started/anta_nrfu_table.sh b/docs/snippets/getting-started/anta_nrfu_table.sh new file mode 100644 index 0000000..785c418 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_table.sh @@ -0,0 +1,10 @@ +anta nrfu \ + --username arista \ + --password arista \ + --inventory ./inventory.yml \ + `# uncomment the next two lines if you have an enable password `\ + `# --enable` \ + `# --enable-password <password>` \ + --catalog ./catalog.yml \ + `# table is default if not provided` \ + table diff --git a/docs/snippets/getting-started/anta_nrfu_text.output b/docs/snippets/getting-started/anta_nrfu_text.output new file mode 100644 index 0000000..872f608 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_text.output @@ -0,0 +1,30 @@ +╭────────────────────── Settings ──────────────────────╮ +│ - ANTA Inventory contains 5 devices (AsyncEOSDevice) │ +│ - Tests catalog contains 9 tests │ +╰──────────────────────────────────────────────────────╯ + +[10:52:39] INFO Preparing ANTA NRFU Run ... tools.py:294 + INFO Connecting to devices ... tools.py:294 + INFO Connecting to devices completed in: 0:00:00.057. tools.py:302 + INFO Preparing the tests ... tools.py:294 + INFO Preparing the tests completed in: 0:00:00.001. tools.py:302 + INFO --- ANTA NRFU Run Information --- runner.py:276 + Number of devices: 5 (5 established) + Total number of selected tests: 45 + Maximum number of open file descriptors for the current ANTA process: 16384 + --------------------------------- + INFO Preparing ANTA NRFU Run completed in: 0:00:00.068. tools.py:302 + INFO Running ANTA tests ... tools.py:294 +[10:52:40] INFO Running ANTA tests completed in: 0:00:00.863. tools.py:302 + INFO Cache statistics for 's1-spine1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-spine2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf1': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf2': 1 hits / 9 command(s) (11.11%) runner.py:75 + INFO Cache statistics for 's1-leaf3': 1 hits / 9 command(s) (11.11%) runner.py:75 + • Running NRFU Tests...100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45/45 • 0:00:00 • 0:00:00 + +s1-spine1 :: VerifyEOSVersion :: FAILURE(device is running version "4.32.2F-38195967.4322F (engineering build)" not in expected versions: ['4.25.4M', '4.26.1F', +'4.28.3M-28837868.4283M (engineering build)']) +s1-spine1 :: VerifyTerminAttrVersion :: FAILURE(device is running TerminAttr version v1.34.0 and is not in the allowed list: ['v1.22.1']) +s1-spine1 :: VerifyZeroTouch :: SUCCESS() +s1-spine1 :: VerifyMlagConfigSanity :: SKIPPED(MLAG is disabled) diff --git a/docs/snippets/getting-started/anta_nrfu_text.sh b/docs/snippets/getting-started/anta_nrfu_text.sh new file mode 100644 index 0000000..3835b51 --- /dev/null +++ b/docs/snippets/getting-started/anta_nrfu_text.sh @@ -0,0 +1,9 @@ +anta nrfu \ + --username arista \ + --password arista \ + --inventory ./inventory.yml \ + `# uncomment the next two lines if you have an enable password `\ + `# --enable` \ + `# --enable-password <password>` \ + --catalog ./catalog.yml \ + text diff --git a/docs/snippets/getting-started/catalog.yml b/docs/snippets/getting-started/catalog.yml new file mode 100644 index 0000000..cc7e781 --- /dev/null +++ b/docs/snippets/getting-started/catalog.yml @@ -0,0 +1,24 @@ +--- +anta.tests.software: + - VerifyEOSVersion: # Verifies the device is running one of the allowed EOS version. + versions: # List of allowed EOS versions. + - 4.25.4M + - 4.26.1F + - '4.28.3M-28837868.4283M (engineering build)' + - VerifyTerminAttrVersion: + versions: + - v1.22.1 + +anta.tests.system: + - VerifyUptime: # Verifies the device uptime is higher than a value. + minimum: 1 + - VerifyNTP: + +anta.tests.mlag: + - VerifyMlagStatus: + - VerifyMlagInterfaces: + - VerifyMlagConfigSanity: + +anta.tests.configuration: + - VerifyZeroTouch: # Verifies ZeroTouch is disabled. + - VerifyRunningConfigDiffs: diff --git a/docs/snippets/getting-started/inventory.yml b/docs/snippets/getting-started/inventory.yml new file mode 100644 index 0000000..2f3d512 --- /dev/null +++ b/docs/snippets/getting-started/inventory.yml @@ -0,0 +1,20 @@ +anta_inventory: + hosts: + - host: 192.168.0.10 + name: s1-spine1 + tags: ['fabric', 'spine'] + - host: 192.168.0.11 + name: s1-spine2 + tags: ['fabric', 'spine'] + - host: 192.168.0.12 + name: s1-leaf1 + tags: ['fabric', 'leaf'] + - host: 192.168.0.13 + name: s1-leaf2 + tags: ['fabric', 'leaf'] + - host: 192.168.0.14 + name: s1-leaf3 + tags: ['fabric', 'leaf'] + - host: 192.168.0.15 + name: s1-leaf3 + tags: ['fabric', 'leaf'] diff --git a/docs/templates/python/material/anta_test_input_model.html.jinja b/docs/templates/python/material/anta_test_input_model.html.jinja new file mode 100644 index 0000000..f867ad0 --- /dev/null +++ b/docs/templates/python/material/anta_test_input_model.html.jinja @@ -0,0 +1,154 @@ +{% if obj.members %} + {{ log.debug("Rendering children of " + obj.path) }} + + <div class="doc doc-children"> + + {% if root_members %} + {% set members_list = config.members %} + {% else %} + {% set members_list = none %} + {% endif %} + + {% if config.group_by_category %} + + {% with %} + + {% if config.show_category_heading %} + {% set extra_level = 1 %} + {% else %} + {% set extra_level = 0 %} + {% endif %} + + {% with attributes = obj.attributes|filter_objects( + filters=config.filters, + members_list=members_list, + inherited_members=config.inherited_members, + keep_no_docstrings=config.show_if_no_docstring, + ) %} + {% if attributes %} + {% if config.show_category_heading %} + {% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %} + {% endif %} + {% with heading_level = heading_level + extra_level %} + {% set root = False %} + {% set heading_level = heading_level + 1 %} + {% set old_obj = obj %} + {% set obj = class %} + {% include "attributes_table.html" with context %} + {% set obj = old_obj %} + {% endwith %} + {% endif %} + {% endwith %} + + {% with classes = obj.classes|filter_objects( + filters=config.filters, + members_list=members_list, + inherited_members=config.inherited_members, + keep_no_docstrings=config.show_if_no_docstring, + ) %} + {% if classes %} + {% if config.show_category_heading %} + {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %} + {% endif %} + {% with heading_level = heading_level + extra_level %} + {% for class in classes|order_members(config.members_order, members_list) %} + {% if members_list is not none or class.is_public %} + {% include class|get_template with context %} + {% endif %} + {% endfor %} + {% endwith %} + {% endif %} + {% endwith %} + + {% with functions = obj.functions|filter_objects( + filters=config.filters, + members_list=members_list, + inherited_members=config.inherited_members, + keep_no_docstrings=config.show_if_no_docstring, + ) %} + {% if functions %} + {% if config.show_category_heading %} + {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %} + {% endif %} + {% with heading_level = heading_level + extra_level %} + {% for function in functions|order_members(config.members_order, members_list) %} + {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %} + {% if members_list is not none or function.is_public %} + {% include function|get_template with context %} + {% endif %} + {% endif %} + {% endfor %} + {% endwith %} + {% endif %} + {% endwith %} + + {% if config.show_submodules %} + {% with modules = obj.modules|filter_objects( + filters=config.filters, + members_list=members_list, + inherited_members=config.inherited_members, + keep_no_docstrings=config.show_if_no_docstring, + ) %} + {% if modules %} + {% if config.show_category_heading %} + {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %} + {% endif %} + {% with heading_level = heading_level + extra_level %} + {% for module in modules|order_members(config.members_order.alphabetical, members_list) %} + {% if members_list is not none or module.is_public %} + {% include module|get_template with context %} + {% endif %} + {% endfor %} + {% endwith %} + {% endif %} + {% endwith %} + {% endif %} + + {% endwith %} + + {% else %} + + {% for child in obj.all_members + |filter_objects( + filters=config.filters, + members_list=members_list, + inherited_members=config.inherited_members, + keep_no_docstrings=config.show_if_no_docstring, + ) + |order_members(config.members_order, members_list) + %} + + {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %} + + {% if members_list is not none or child.is_public %} + {% if child.is_attribute %} + {% with attribute = child %} + {% include attribute|get_template with context %} + {% endwith %} + + {% elif child.is_class %} + {% with class = child %} + {% include class|get_template with context %} + {% endwith %} + + {% elif child.is_function %} + {% with function = child %} + {% include function|get_template with context %} + {% endwith %} + + {% elif child.is_module and config.show_submodules %} + {% with module = child %} + {% include module|get_template with context %} + {% endwith %} + + {% endif %} + {% endif %} + + {% endif %} + + {% endfor %} + + {% endif %} + + </div> +{% endif %} diff --git a/docs/templates/python/material/class.html.jinja b/docs/templates/python/material/class.html.jinja index 1c1173c..cbf9fac 100644 --- a/docs/templates/python/material/class.html.jinja +++ b/docs/templates/python/material/class.html.jinja @@ -1,26 +1,46 @@ {% extends "_base/class.html.jinja" %} {% set anta_test = namespace(found=false) %} +{% set anta_test_input_model = namespace(found=false) %} {% for base in class.bases %} {% set basestr = base | string %} {% if "AntaTest" == basestr %} {% set anta_test.found = True %} {% endif %} {% endfor %} +{# TODO make this nicer #} +{% if class.parent.parent.name == "input_models" or class.parent.parent.parent.name == "input_models" %} +{% set anta_test_input_model.found = True %} +{% endif %} {% block children %} {% if anta_test.found %} {% set root = False %} {% set heading_level = heading_level + 1 %} {% include "anta_test.html.jinja" with context %} {# render source after children - TODO make add flag to respect disabling it.. though do we want to disable?#} - <details class="quote"> - <summary>Source code in <code> - {%- if class.relative_filepath.is_absolute() -%} - {{ class.relative_package_filepath }} - {%- else -%} - {{ class.relative_filepath }} - {%- endif -%} - </code></summary> - {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }} + <details class="quote"> + <summary>Source code in <code> + {%- if class.relative_filepath.is_absolute() -%} + {{ class.relative_package_filepath }} + {%- else -%} + {{ class.relative_filepath }} + {%- endif -%} + </code></summary> + {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }} + </details> +{% elif anta_test_input_model.found %} + {% set root = False %} + {% set heading_level = heading_level + 1 %} + {% include "anta_test_input_model.html.jinja" with context %} + {# render source after children - TODO make add flag to respect disabling it.. though do we want to disable?#} + <details class="quote"> + <summary>Source code in <code> + {%- if class.relative_filepath.is_absolute() -%} + {{ class.relative_package_filepath }} + {%- else -%} + {{ class.relative_filepath }} + {%- endif -%} + </code></summary> + {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }} </details> {% else %} {{ super() }} @@ -29,7 +49,25 @@ {# Do not render source before children for AntaTest #} {% block source %} -{% if not anta_test.found %} +{% if not anta_test.found and not anta_test_input_model%} {{ super() }} {% endif %} {% endblock source %} + +{# overwrite block base to render some stuff on deprecation for anta_test #} +{% block bases %} +{{ super() }} + +{% for dec in class.decorators %} +{% if dec.value.function.name == "deprecated_test_class" %} +<img alt="Static Badge" src="https://img.shields.io/badge/DEPRECATED-yellow?style=flat&logoSize=auto"> +{% for arg in dec.value.arguments | selectattr("name", "equalto", "removal_in_version") | list %} +<img alt="Static Badge" src="https://img.shields.io/badge/REMOVAL-{{ arg.value[1:-1] }}-grey?style=flat&logoSize=auto&labelColor=red"> +{% endfor %} +<br/> +{% for arg in dec.value.arguments | selectattr("name", "equalto", "new_tests") | list %} +<strong>Replaced with:</strong> {{ arg.value.elements | map("replace", "'", "<code>", 1) | map("replace", "'", "</code>", 1) | join(", ") | safe }} +{% endfor %} +{% endif %} +{% endfor %} +{% endblock bases %} diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 25b061c..a422f7c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -33,9 +33,8 @@ To help document the issue in Github, it is important to capture some logs so th 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. +> [!CAUTION] +> 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: @@ -46,11 +45,10 @@ anta -l DEBUG –log-file anta.log <ANTA_COMMAND> See `anta --help` for more information. These have to precede the `nrfu` cmd. -!!! tip - - Remember that in ANTA, each level of command has its own options and they can only be set at this level. - 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`). +> [!TIP] +> Remember that in ANTA, each level of command has its own options and they can only be set at this level. +> 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: @@ -60,9 +58,8 @@ anta -l DEBUG --log-file anta.log nrfu --enable --username username --password a ### `ANTA_DEBUG` environment variable -!!! 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. +> [!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. The environment variable `ANTA_DEBUG=true` enable ANTA Debug Mode. diff --git a/docs/usage-inventory-catalog.md b/docs/usage-inventory-catalog.md index e41321a..7baebfb 100644 --- a/docs/usage-inventory-catalog.md +++ b/docs/usage-inventory-catalog.md @@ -47,8 +47,8 @@ The inventory file must start with the `anta_inventory` key then define one or m A full description of the inventory model is available in [API documentation](api/inventory.models.input.md) -!!! info - Caching can be disabled per device, network or range by setting the `disable_cache` key to `True` in the inventory file. For more details about how caching is implemented in ANTA, please refer to [Caching in ANTA](advanced_usages/caching.md). +> [!INFO] +> Caching can be disabled per device, network or range by setting the `disable_cache` key to `True` in the inventory file. For more details about how caching is implemented in ANTA, please refer to [Caching in ANTA](advanced_usages/caching.md). ### Example @@ -199,8 +199,8 @@ anta.tests.system: tags: ['leaf'] ``` -!!! info - When using the CLI, you can filter the NRFU execution using tags. Refer to [this section](cli/tag-management.md) of the CLI documentation. +> [!INFO] +> When using the CLI, you can filter the NRFU execution using tags. Refer to [this section](cli/tag-management.md) of the CLI documentation. ### Tests available in ANTA @@ -277,8 +277,10 @@ custom.tests.system: type: ['cEOS-LAB'] ``` -!!! tip "How to create custom tests" - To create your custom tests, you should refer to this [documentation](advanced_usages/custom-tests.md) +> [!TIP] +> **How to create custom tests** +> +> To create your custom tests, you should refer to this [documentation](advanced_usages/custom-tests.md) ### Customize test description and categories @@ -317,5 +319,5 @@ The following script reads all the files in `intended/test_catalogs/` with names --8<-- "merge_catalogs.py" ``` -!!! warning - The `AntaCatalog.merge()` method is deprecated and will be removed in ANTA v2.0. Please use the `AntaCatalog.merge_catalogs()` class method instead. +> [!WARNING] +> The `AntaCatalog.merge()` method is deprecated and will be removed in ANTA v2.0. Please use the `AntaCatalog.merge_catalogs()` class method instead. |