Adding upstream version 0.13.0.upstream/0.13.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 175 insertions, 0 deletions

diff --git a/docs/cli/debug.md b/docs/cli/debug.md
new file mode 100644
index 0000000..1743c7a
--- /dev/null
+++ b/docs/cli/debug.md
@@ -0,0 +1,175 @@
+<!--
+  ~ 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.
+  -->
+
+# 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](../contribution.md).
+
+!!! warning
+    The `debug` tools require a device from your inventory. Thus, you MUST use a valid [ANTA Inventory](../usage-inventory-catalog.md#create-an-inventory-file).
+
+## Executing an EOS command
+
+You can use the `run-cmd` entrypoint to run a command, which includes the following options:
+
+### Command overview
+
+```bash
+$ anta debug run-cmd --help
+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 INTEGER         Global connection timeout  [env var: ANTA_TIMEOUT;
+                            default: 30]
+  --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]
+  -t, --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):
+
+```bash
+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`](https://realpython.com/python-f-strings/#f-strings-a-new-and-improved-way-to-format-strings-in-python) templated command. It is followed by a list of arguments (key-value pairs) that build a dictionary used as template parameters.
+
+### Command overview
+
+```bash
+$ anta debug run-template --help
+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 INTEGER         Global connection timeout  [env var: ANTA_TIMEOUT;
+                            default: 30]
+  --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]
+  -t, --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:
+
+```bash
+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
+
+```bash
+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
+```