Inventory and Catalog¶
The ANTA framework needs 2 important inputs from the user to run: a device inventory and a test catalog.
Both inputs can be defined in a file or programmatically.
Device Inventory¶
A device inventory is an instance of the AntaInventory class.
Device Inventory File¶
The ANTA device inventory can easily be defined as a YAML file. The file must comply with the following structure:
anta_inventory:
hosts:
- host: < ip address value >
port: < TCP port for eAPI. Default is 443 (Optional)>
name: < name to display in report. Default is host:port (Optional) >
tags: < list of tags to use to filter inventory during tests >
disable_cache: < Disable cache per hosts. Default is False. >
networks:
- network: < network using CIDR notation >
tags: < list of tags to use to filter inventory during tests >
disable_cache: < Disable cache per network. Default is False. >
ranges:
- start: < first ip address value of the range >
end: < last ip address value of the range >
tags: < list of tags to use to filter inventory during tests >
disable_cache: < Disable cache per range. Default is False. >
The inventory file must start with the anta_inventory key then define one or multiple methods:
hosts: define each device individuallynetworks: scan a network for devices accessible via eAPIranges: scan a range for devices accessible via eAPI
A full description of the inventory model is available in API documentation
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.
Example¶
---
anta_inventory:
hosts:
- host: 192.168.0.10
name: spine01
tags: ['fabric', 'spine']
- host: 192.168.0.11
name: spine02
tags: ['fabric', 'spine']
networks:
- network: '192.168.110.0/24'
tags: ['fabric', 'leaf']
ranges:
- start: 10.0.0.9
end: 10.0.0.11
tags: ['fabric', 'l2leaf']
Test Catalog¶
A test catalog is an instance of the AntaCatalog class.
Test Catalog File¶
In addition to the inventory file, you also have to define a catalog of tests to execute against your devices. This catalog list all your tests, their inputs and their tags.
A valid test catalog file must have the following structure:
---
<Python module>:
- <AntaTest subclass>:
<AntaTest.Input compliant dictionary>
Example¶
---
anta.tests.connectivity:
- VerifyReachability:
hosts:
- source: Management0
destination: 1.1.1.1
vrf: MGMT
- source: Management0
destination: 8.8.8.8
vrf: MGMT
filters:
tags: ['leaf']
result_overwrite:
categories:
- "Overwritten category 1"
description: "Test with overwritten description"
custom_field: "Test run by John Doe"
It is also possible to nest Python module definition:
anta.tests:
connectivity:
- VerifyReachability:
hosts:
- source: Management0
destination: 1.1.1.1
vrf: MGMT
- source: Management0
destination: 8.8.8.8
vrf: MGMT
filters:
tags: ['leaf']
result_overwrite:
categories:
- "Overwritten category 1"
description: "Test with overwritten description"
custom_field: "Test run by John Doe"
This test catalog example is maintained with all the tests defined in the anta.tests Python module.
Test tags¶
All tests can be defined with a list of user defined tags. These tags will be mapped with device tags: when at least one tag is defined for a test, this test will only be executed on devices with the same tag. If a test is defined in the catalog without any tags, the test will be executed on all devices.
anta.tests.system:
- VerifyUptime:
minimum: 10
filters:
tags: ['demo', 'leaf']
- VerifyReloadCause:
- VerifyCoredump:
- VerifyAgentLogs:
- VerifyCPUUtilization:
filters:
tags: ['leaf']
Info
When using the CLI, you can filter the NRFU execution using tags. Refer to this section of the CLI documentation.
Tests available in ANTA¶
All tests available as part of the ANTA framework are defined under the anta.tests Python module and are categorised per family (Python submodule).
The complete list of the tests and their respective inputs is available at the tests section of this website.
To run test to verify the EOS software version, you can do:
anta.tests.software:
- VerifyEOSVersion:
It will load the test VerifyEOSVersion located in anta.tests.software. But since this test has mandatory inputs, we need to provide them as a dictionary in the YAML file:
anta.tests.software:
- VerifyEOSVersion:
# List of allowed EOS versions.
versions:
- 4.25.4M
- 4.26.1F
The following example is a very minimal test catalog:
---
# Load anta.tests.software
anta.tests.software:
# Verifies the device is running one of the allowed EOS version.
- VerifyEOSVersion:
# List of allowed EOS versions.
versions:
- 4.25.4M
- 4.26.1F
# Load anta.tests.system
anta.tests.system:
# Verifies the device uptime is higher than a value.
- VerifyUptime:
minimum: 1
# Load anta.tests.configuration
anta.tests.configuration:
# Verifies ZeroTouch is disabled.
- VerifyZeroTouch:
- VerifyRunningConfigDiffs:
Catalog with custom tests¶
In case you want to leverage your own tests collection, use your own Python package in the test catalog.
So for instance, if my custom tests are defined in the titom73.tests.system Python module, the test catalog will be:
titom73.tests.system:
- VerifyPlatform:
type: ['cEOS-LAB']
How to create custom tests
To create your custom tests, you should refer to this documentation
Customize test description and categories¶
It might be interesting to use your own categories and customized test description to build a better report for your environment. ANTA comes with a handy feature to define your own categories and description in the report.
In your test catalog, use result_overwrite dictionary with categories and description to just overwrite this values in your report:
anta.tests.configuration:
- VerifyZeroTouch: # Verifies ZeroTouch is disabled.
result_overwrite:
categories: ['demo', 'pr296']
description: A custom test
- VerifyRunningConfigDiffs:
anta.tests.interfaces:
- VerifyInterfaceUtilization:
Once you run anta nrfu table, you will see following output:
┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
┃ Device IP ┃ Test Name ┃ Test Status ┃ Message(s) ┃ Test description ┃ Test category ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
│ spine01 │ VerifyZeroTouch │ success │ │ A custom test │ demo, pr296 │
│ spine01 │ VerifyRunningConfigDiffs │ success │ │ │ configuration │
│ spine01 │ VerifyInterfaceUtilization │ success │ │ Verifies interfaces utilization is below 75%. │ interfaces │
└───────────┴────────────────────────────┴─────────────┴────────────┴───────────────────────────────────────────────┴───────────────┘
Example script to merge catalogs¶
The following script reads all the files in intended/test_catalogs/ with names <device_name>-catalog.yml and merge them together inside one big catalog anta-catalog.yml.
#!/usr/bin/env python
from anta.catalog import AntaCatalog
from pathlib import Path
from anta.models import AntaTest
CATALOG_SUFFIX = '-catalog.yml'
CATALOG_DIR = 'intended/test_catalogs/'
if __name__ == "__main__":
catalog = AntaCatalog()
for file in Path(CATALOG_DIR).glob('*'+CATALOG_SUFFIX):
c = AntaCatalog.parse(file)
device = str(file).removesuffix(CATALOG_SUFFIX).removeprefix(CATALOG_DIR)
print(f"Merging test catalog for device {device}")
# Apply filters to all tests for this device
for test in c.tests:
test.inputs.filters = AntaTest.Input.Filters(tags=[device])
catalog = catalog.merge(c)
with open(Path('anta-catalog.yml'), "w") as f:
f.write(catalog.dump().yaml())