Helpers

ANTA debug commands¶

The ANTA CLI includes a set of debugging tools, making it easier to build and test ANTA content. This functionality is accessed via the debug subcommand and offers the following options:

Executing a command on a device from your inventory and retrieving the result.
Running a templated command on a device from your inventory and retrieving the result.

These tools are especially helpful in building the tests, as they give a visual access to the output received from the eAPI. They also facilitate the extraction of output content for use in unit tests, as described in our contribution guide.

Warning

The debug tools require a device from your inventory. Thus, you MUST use a valid ANTA Inventory.

Executing an EOS command¶

You can use the run-cmd entrypoint to run a command, which includes the following options:

Command overview¶

Usage: anta debug run-cmd [OPTIONS]

  Run arbitrary command to an ANTA device.

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]
  --ofmt [json|text]        EOS eAPI format to use. can be text or json
  -v, --version [1|latest]  EOS eAPI version
  -r, --revision INTEGER    eAPI command revision
  -d, --device TEXT         Device from inventory to use  [required]
  -c, --command TEXT        Command to run  [required]
  --help                    Show this message and exit.

username, password, enable-password, enable, timeout and insecure values are the same for all devices

Example¶

This example illustrates how to run the show interfaces description command with a JSON format (default):

anta debug run-cmd --command "show interfaces description" --device DC1-SPINE1
Run command show interfaces description on DC1-SPINE1
{
    'interfaceDescriptions': {
        'Ethernet1': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-LEAF1A_Ethernet1', 'interfaceStatus': 'up'},
        'Ethernet2': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-LEAF1B_Ethernet1', 'interfaceStatus': 'up'},
        'Ethernet3': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-BL1_Ethernet1', 'interfaceStatus': 'up'},
        'Ethernet4': {'lineProtocolStatus': 'up', 'description': 'P2P_LINK_TO_DC1-BL2_Ethernet1', 'interfaceStatus': 'up'},
        'Loopback0': {'lineProtocolStatus': 'up', 'description': 'EVPN_Overlay_Peering', 'interfaceStatus': 'up'},
        'Management0': {'lineProtocolStatus': 'up', 'description': 'oob_management', 'interfaceStatus': 'up'}
    }
}

Executing an EOS command using templates¶

The run-template entrypoint allows the user to provide an f-string templated command. It is followed by a list of arguments (key-value pairs) that build a dictionary used as template parameters.

Command overview¶

Usage: anta debug run-template [OPTIONS] PARAMS...

  Run arbitrary templated command to an ANTA device.

  Takes a list of arguments (keys followed by a value) to build a dictionary
  used as template parameters.

  Example: ------- anta debug run-template -d leaf1a -t 'show vlan {vlan_id}'
  vlan_id 1

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]
  --ofmt [json|text]        EOS eAPI format to use. can be text or json
  -v, --version [1|latest]  EOS eAPI version
  -r, --revision INTEGER    eAPI command revision
  -d, --device TEXT         Device from inventory to use  [required]
  -t, --template TEXT       Command template to run. E.g. 'show vlan
                            {vlan_id}'  [required]
  --help                    Show this message and exit.

username, password, enable-password, enable, timeout and insecure values are the same for all devices

Example¶

This example uses the show vlan {vlan_id} command in a JSON format:

anta debug run-template --template "show vlan {vlan_id}" vlan_id 10 --device DC1-LEAF1A
Run templated command 'show vlan {vlan_id}' with {'vlan_id': '10'} on DC1-LEAF1A
{
    'vlans': {
        '10': {
            'name': 'VRFPROD_VLAN10',
            'dynamic': False,
            'status': 'active',
            'interfaces': {
                'Cpu': {'privatePromoted': False, 'blocked': None},
                'Port-Channel11': {'privatePromoted': False, 'blocked': None},
                'Vxlan1': {'privatePromoted': False, 'blocked': None}
            }
        }
    },
    'sourceDetail': ''
}

Warning

If multiple arguments of the same key are provided, only the last argument value will be kept in the template parameters.

Example of multiple arguments¶

anta -log DEBUG debug run-template --template "ping {dst} source {src}" dst "8.8.8.8" src Loopback0 --device DC1-SPINE1    
> {'dst': '8.8.8.8', 'src': 'Loopback0'}

anta -log DEBUG debug run-template --template "ping {dst} source {src}" dst "8.8.8.8" src Loopback0 dst "1.1.1.1" src Loopback1 --device DC1-SPINE1          
> {'dst': '1.1.1.1', 'src': 'Loopback1'}
# Notice how `src` and `dst` keep only the latest value