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¶
The easiest way to install ANTA package is to run Python (>=3.9) and its pip package to install:
pip install anta[cli]
For more details about how to install package, please see the requirements and installation section.
Configure Arista EOS devices¶
For ANTA to be able to connect to your target devices, you need to configure your management interface
vrf instance MGMT
!
interface Management0
description oob_management
vrf MGMT
ip address 192.168.0.10/24
!
Then, configure access to eAPI:
!
management api http-commands
protocol https port 443
no shutdown
vrf MGMT
no shutdown
!
!
Create your inventory¶
ANTA uses an inventory to list the target devices for the tests. You can create a file manually with this format:
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']
You can read more details about how to build your inventory here
Test Catalog¶
To test your network, ANTA relies on a test catalog to list all the tests to run against your inventory. A test catalog references python functions into a yaml file.
The structure to follow is like:
<anta_tests_submodule>:
- <anta_tests_submodule function name>:
<test function option>:
<test function option value>
You can read more details about how to build your catalog here
Here is an example for basic tests:
---
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:
Test your network¶
CLI¶
ANTA comes with a generic CLI entrypoint to run tests in your network. It requires an inventory file as well as a test catalog.
This entrypoint has multiple options to manage test coverage and reporting.
Usage: anta [OPTIONS] COMMAND [ARGS]...
Arista Network Test Automation (ANTA) CLI.
Options:
--version Show the version and exit.
--log-file FILE Send the logs to a file. If logging level is
DEBUG, only INFO or higher will be sent to
stdout. [env var: ANTA_LOG_FILE]
-l, --log-level [CRITICAL|ERROR|WARNING|INFO|DEBUG]
ANTA logging level [env var:
ANTA_LOG_LEVEL; default: INFO]
--help Show this message and exit.
Commands:
check Commands to validate configuration files.
debug Commands to execute EOS commands on remote devices.
exec Commands to execute various scripts on EOS devices.
get Commands to get information from or generate inventories.
nrfu Run ANTA tests on selected inventory devices.
Usage: anta nrfu [OPTIONS] COMMAND [ARGS]...
Run ANTA tests on selected inventory devices.
Options:
-u, --username TEXT Username to connect to EOS [env var:
ANTA_USERNAME; required]
-p, --password TEXT Password to connect to EOS that must be
provided. It can be prompted using '--
prompt' option. [env var: ANTA_PASSWORD]
--enable-password TEXT Password to access EOS Privileged EXEC mode.
It can be prompted using '--prompt' option.
Requires '--enable' option. [env var:
ANTA_ENABLE_PASSWORD]
--enable Some commands may require EOS Privileged
EXEC mode. This option tries to access this
mode before sending a command to the device.
[env var: ANTA_ENABLE]
-P, --prompt Prompt for passwords if they are not
provided. [env var: ANTA_PROMPT]
--timeout FLOAT Global API timeout. This value will be used
for all devices. [env var: ANTA_TIMEOUT;
default: 30.0]
--insecure Disable SSH Host Key validation. [env var:
ANTA_INSECURE]
--disable-cache Disable cache globally. [env var:
ANTA_DISABLE_CACHE]
-i, --inventory FILE Path to the inventory YAML file. [env var:
ANTA_INVENTORY; required]
--tags TEXT List of tags using comma as separator:
tag1,tag2,tag3. [env var: ANTA_TAGS]
-c, --catalog FILE Path to the test catalog file [env var:
ANTA_CATALOG; required]
--catalog-format [yaml|json] Format of the catalog file, either 'yaml' or
'json' [env var: ANTA_CATALOG_FORMAT]
-d, --device TEXT Run tests on a specific device. Can be
provided multiple times.
-t, --test TEXT Run a specific test. Can be provided
multiple times.
--ignore-status Exit code will always be 0. [env var:
ANTA_NRFU_IGNORE_STATUS]
--ignore-error Exit code will be 0 if all tests succeeded
or 1 if any test failed. [env var:
ANTA_NRFU_IGNORE_ERROR]
--hide [success|failure|error|skipped]
Hide results by type: success / failure /
error / skipped'.
--dry-run Run anta nrfu command but stop before
starting to execute the tests. Considers all
devices as connected. [env var:
ANTA_NRFU_DRY_RUN]
--help Show this message and exit.
Commands:
csv ANTA command to check network state with CSV report.
json ANTA command to check network state with JSON results.
md-report ANTA command to check network state with Markdown report.
table ANTA command to check network state with table results.
text ANTA command to check network state with text results.
tpl-report ANTA command to check network state with templated report.
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
Default report using table¶
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
╭────────────────────── 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 │
└───────────┴──────────────────────────┴─────────────┴────────────────────────────────────────────┴────────────────────────────────────────────┴───────────────┘
Report in text mode¶
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
╭────────────────────── 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)
Report in JSON format¶
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
╭────────────────────── 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
},
[...]
Basic usage in a Python script¶
# 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.
"""Example script for ANTA.
usage:
python anta_runner.py
"""
from __future__ import annotations
import asyncio
import logging
import sys
from pathlib import Path
from anta.catalog import AntaCatalog
from anta.cli.nrfu.utils import anta_progress_bar
from anta.inventory import AntaInventory
from anta.logger import Log, setup_logging
from anta.models import AntaTest
from anta.result_manager import ResultManager
from anta.runner import main as anta_runner
# setup logging
setup_logging(Log.INFO, Path("/tmp/anta.log"))
LOGGER = logging.getLogger()
SCRIPT_LOG_PREFIX = "[bold magenta][ANTA RUNNER SCRIPT][/] " # For convenience purpose - there are nicer way to do this.
# NOTE: The inventory and catalog files are not delivered with this script
USERNAME = "admin"
PASSWORD = "admin"
CATALOG_PATH = Path("/tmp/anta_catalog.yml")
INVENTORY_PATH = Path("/tmp/anta_inventory.yml")
# Load catalog file
try:
catalog = AntaCatalog.parse(CATALOG_PATH)
except Exception:
LOGGER.exception("%s Catalog failed to load!", SCRIPT_LOG_PREFIX)
sys.exit(1)
LOGGER.info("%s Catalog loaded!", SCRIPT_LOG_PREFIX)
# Load inventory
try:
inventory = AntaInventory.parse(INVENTORY_PATH, username=USERNAME, password=PASSWORD)
except Exception:
LOGGER.exception("%s Inventory failed to load!", SCRIPT_LOG_PREFIX)
sys.exit(1)
LOGGER.info("%s Inventory loaded!", SCRIPT_LOG_PREFIX)
# Create result manager object
manager = ResultManager()
# Launch ANTA
LOGGER.info("%s Starting ANTA runner...", SCRIPT_LOG_PREFIX)
with anta_progress_bar() as AntaTest.progress:
# Set dry_run to True to avoid connecting to the devices
asyncio.run(anta_runner(manager, inventory, catalog, dry_run=False))
LOGGER.info("%s ANTA run completed!", SCRIPT_LOG_PREFIX)
# Manipulate the test result object
for test_result in manager.results:
LOGGER.info("%s %s:%s:%s", SCRIPT_LOG_PREFIX, test_result.name, test_result.test, test_result.result)