Skip to content

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: 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']

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:

# 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:

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

Default report using table
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 │
└───────────┴──────────────────────────┴─────────────┴──────────────────┴──────────────────────────────────────────────────────────────────────┴───────────────┘
Report in text mode
$ 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)
[...]
Report in JSON format
$ 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",
  },
[...]
]

You can find more information under the usage section of the website

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)