Migrate to anta_runner¶

This guide helps you migrate from the deprecated arista.avd.eos_validate_state role to the new arista.avd.anta_runner role.

Note

The eos_validate_state role was deprecated in AVD 5.7 and removed in AVD 6.0.0. The anta_runner role provides the same functionality with additional features and improvements.

For full documentation on the anta_runner role, see the anta_runner documentation.

Quick Start¶

To use the new role, update the role name in your playbook. It is a good idea to also update the play name and task name for clarity.

  ---
  - name: Run ANTA
    hosts: FABRIC
    connection: local
    gather_facts: false
    tasks:
      - name: Run ANTA on EOS devices
        import_role:
-         name: arista.avd.eos_validate_state
+         name: arista.avd.anta_runner

This basic migration is enough to get started. However, because there are functional differences between the two roles, you must adjust your playbooks and inventory to maintain the behavior of eos_validate_state. Review the sections below to identify the specific changes required for your environment.

Directory Structure Changes¶

In the legacy eos_validate_state role, output files were split between the intended and reports directories. With anta_runner, all files generated by the role are consolidated under a single anta directory by default.

eos_validate_stateanta_runner

inventory/
├── intended/
│   ├── structured_configs/
│   └── test_catalogs/          # Optional: saved catalogs (save_catalog: true)
├── custom_anta_catalogs/       # Custom catalogs
└── reports/
    ├── test_results/           # JSON results per device
    ├── FABRIC-state.csv
    └── FABRIC-state.md

inventory/
├── intended/
│   └── structured_configs/
└── anta/
    ├── avd_catalogs/           # AVD-generated catalogs per device (always saved)
    ├── user_catalogs/          # User-defined catalogs (previously called custom catalogs)
    └── reports/
        ├── anta_report.json
        ├── anta_report.csv
        └── anta_report.md

To customize directory and report paths in anta_runner:

avd_catalogs_dir: "{{ inventory_dir }}/anta/avd_catalogs"
user_catalogs_dir: "{{ inventory_dir }}/anta/user_catalogs"
anta_reports_dir: "{{ inventory_dir }}/anta/reports"
anta_report_md_path: "{{ anta_reports_dir }}/anta_report.md"
anta_report_csv_path: "{{ anta_reports_dir }}/anta_report.csv"
anta_report_json_path: "{{ anta_reports_dir }}/anta_report.json"

Custom ANTA Catalogs¶

In eos_validate_state, custom ANTA catalogs were automatically loaded from the custom_anta_catalogs_dir directory. In anta_runner, these catalogs are now referred to as user-defined catalogs. To load user-defined catalogs, you must explicitly enable the feature:

user_catalogs_enabled: true

Additionally, the device targeting mechanism has changed:

In eos_validate_state, catalogs were targeted to specific Ansible inventory hosts or groups based on the filename (<hostname>.yml, <group>.yml, or all.yml).
In anta_runner, all catalogs are merged together and targeting is done using tags in the catalog files and anta_tags in the Ansible inventory.

eos_validate_stateanta_runner

custom_anta_catalogs/DC1_LEAFS.yml

# Applied to all devices in DC1_LEAFS group based on filename
anta.tests.vxlan:
  - VerifyVxlan1Interface:

user_catalogs/vxlan_tests.yml

# Tag the test to target specific devices
anta.tests.vxlan:
  - VerifyVxlan1Interface:
      filters:
        tags: [ leaf ]

inventory.yml

# Assign anta_tags to devices
all:
  children:
    DC1_LEAFS:
      hosts:
        DC1-LEAF1A:
          anta_tags: [ leaf ]
        DC1-LEAF1B:
          anta_tags: [ leaf ]

For more details on tag-based filtering, see Tag-Based Filtering.

Generated Catalogs Storage¶

In eos_validate_state, saving test catalogs was optional and controlled by save_catalog. When enabled, the saved catalog included both AVD-generated tests and custom catalog tests merged together into a single file.

In anta_runner, test catalogs are always saved, but they only include AVD-generated tests. User-defined tests are excluded from the saved catalogs.

Note

This is acceptable because user-defined catalogs now use tag-based targeting instead of filename-based targeting, so the merged catalog is no longer needed for debugging or inspection.

To disable AVD-generated catalogs entirely (for example, when running only user-defined catalogs), use avd_catalogs_enabled:

# Disable AVD-generated catalogs
avd_catalogs_enabled: false
# Enable user-defined catalogs only
user_catalogs_enabled: true

Test Filtering¶

The skip_tests variable has been replaced with avd_catalogs_filters. The key difference is that anta_runner no longer uses AVD test categories (e.g., AvdTestHardware, AvdTestNTP). Instead, you specify ANTA test class names directly (e.g., VerifyNTP, VerifyEnvironmentPower).

eos_validate_stateanta_runner

skip_tests:
  - category: AvdTestHardware
  - category: AvdTestNTP

avd_catalogs_filters:
  - skip_tests:
      - VerifyEnvironmentPower
      - VerifyEnvironmentCooling
      - VerifyTemperature
      - VerifyTransceiversManufacturers
      - VerifyNTP

Note

The anta_runner role generates additional tests compared to eos_validate_state. If you want to skip these additional tests, you can use the avd_catalogs_filters variable shown above.

For a complete list of available ANTA test names, see the AVD-generated Catalog Test Index. For additional filtering options, see Test-Based Filtering.

Logging Verbosity¶

In eos_validate_state, logging verbosity was controlled by the logging_level variable.

In anta_runner, logging verbosity is controlled by Ansible standard verbosity flags (-v, -vv, -vvv, -vvvv):

eos_validate_stateanta_runner

logging_level: "DEBUG"  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL

# Use Ansible verbosity flags instead
ansible-playbook playbooks/fabric-validate.yaml -vvv

For more details, see Logging and Troubleshooting.

Dry Run Mode¶

The anta_runner role does not support Ansible check mode (--check). To generate tests without executing them, use the anta_runner_dry_run variable instead:

eos_validate_stateanta_runner

ansible-playbook playbooks/fabric-validate.yaml --check

anta_runner_dry_run: true

Report Generation¶

Showing Only Failed Tests¶

In eos_validate_state, the only_failed_tests variable controlled whether reports showed only failed tests.

In anta_runner, use anta_report_exclude_statuses to exclude specific test statuses from reports:

eos_validate_stateanta_runner

only_failed_tests: true

anta_report_exclude_statuses: [ success, skipped ]

Disabling Report Generation¶

In eos_validate_state, CSV and Markdown report generations were controlled by boolean variables.

In anta_runner, set the report path to null to disable generation of a specific report format:

eos_validate_stateanta_runner

validation_report_csv: false
validation_report_md: false

# Set to null to disable
anta_report_csv_path: null
anta_report_md_path: null

Markdown Report Formatting¶

The anta_runner role has different default report formatting compared to eos_validate_state:

Condensed results: By default, test results are grouped in the report to avoid large report files on high-scale fabrics. To show individual test entries like eos_validate_state, use anta_report_expand_results.
Custom field hidden: By default, the custom_field column is hidden. To show it like eos_validate_state, use anta_report_custom_field.

# Expand results to show individual test inputs
anta_report_expand_results: true
# Include the custom_field column in Markdown reports
anta_report_custom_field: true

Fan and Power Supply States¶

The ANTA tests for fan and power supply validation have been improved. The accepted_fan_states and accepted_pwr_supply_states variables are no longer required.

If you are expecting that not all fans and power supplies are inserted in specific devices, you can use validation profiles to define the expected number of fans and power supplies.

eos_validate_stateanta_runner

# No longer required
accepted_fan_states: [ ok ]
accepted_pwr_supply_states: [ ok ]

# eos_designs configuration
validation_profiles:
  - name: chassis_profile
    hardware:
      min_power_supplies: 2  # Set to 0 to skip validation
      min_fans: 4            # Set to 0 to skip validation

# Apply to node types
spine:
  defaults:
    validation_profile: chassis_profile

For more details, see Validation Profiles.

Transceiver Manufacturers¶

In eos_validate_state, accepted transceiver manufacturers were configured using the accepted_xcvr_manufacturers variable.

In anta_runner, this setting has moved to eos_designs and is configured through validation_profiles:

eos_validate_stateanta_runner

accepted_xcvr_manufacturers:
  - Arista Networks
  - Arastra, Inc.
  - Third Party Vendor

# eos_designs configuration
validation_profiles:
  - name: datacenter
    hardware:
      transceiver_manufacturers:
        - Arista Networks
        - Arastra, Inc.
        - Third Party Vendor

# Apply to node types
spine:
  defaults:
    validation_profile: datacenter
l3leaf:
  defaults:
    validation_profile: datacenter

For more details, see Validation Profiles.

Fabric-Wide Validation¶

In eos_validate_state, fabric-wide validation tests were generated by default. These tests include:

Loopback0 reachability
VTEP reachability
Inband management reachability
DPS reachability
Routing table entries for fabric underlay

In anta_runner, these tests are disabled by default.

Note

This change was made because these tests can generate many additional test inputs and significantly increase execution time in large-scale deployments.

To enable fabric-wide tests:

avd_catalogs_extra_fabric_validation: true

For more details, see Extra Fabric Validation.

Hardware Validation on Virtual Platforms¶

In eos_validate_state, hardware tests were generated for all platforms, but ANTA would skip them on virtual platforms and show them as “skipped” in the report.

In anta_runner, hardware tests are not generated for known virtual platforms by default. This means these tests will be absent from the report rather than appearing as “skipped”.

This behavior is controlled by feature_support.hardware_validation in eos_designs platform settings. The following platforms have this set to false by default:

vEOS: VEOS, VEOS-LAB, vEOS, vEOS-lab
cEOS: CEOS, cEOS, ceos, cEOSLab
CloudEOS: CloudEOS

To get the same behavior as eos_validate_state (hardware tests generated and skipped by ANTA), you can use custom_platform_settings:

custom_platform_settings:
  - platforms:
      - VEOS
      - VEOS-LAB
      - vEOS
      - vEOS-lab
      - CEOS
      - cEOS
      - ceos
      - cEOSLab
      - CloudEOS
    feature_support:
      hardware_validation: true

Complete Migration Example¶

The following example shows a complete migration from eos_validate_state to anta_runner with equivalent behavior:

eos_validate_stateanta_runner

- name: Validate Network State
  hosts: FABRIC
  connection: local
  gather_facts: false
  tasks:
    - name: Validate states on EOS devices
      import_role:
        name: arista.avd.eos_validate_state
      vars:
        save_catalog: true
        only_failed_tests: true

- name: Validate Network State
  hosts: FABRIC
  connection: local
  gather_facts: false
  tasks:
    - name: Run ANTA on EOS devices
      import_role:
        name: arista.avd.anta_runner
      vars:
        avd_catalogs_extra_fabric_validation: true # (1)!
        anta_report_exclude_statuses: [ success, skipped ] # (2)!
        anta_report_expand_results: true # (3)!
        anta_report_custom_field: true # (4)!

Enable fabric-wide validation tests (default in eos_validate_state)
Equivalent to only_failed_tests: true
Equivalent Markdown report test results granularity
Equivalent Markdown report columns formatting

For information about new features available in anta_runner, see the anta_runner documentation.

Additional Resources¶

ANTA Framework Documentation