Skip to content

Commit

Permalink
Fixed doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@carl-baillargeon
carl-baillargeon committed Jul 15, 2023
1 parent 1421aed commit 61618e2
Show file tree
Hide file tree
Showing 11 changed files with 331 additions and 206 deletions.
38 changes: 24 additions & 14 deletions docs/cli/debug.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
# ANTA debug commands
# Debugging ANTA Commands

ANTA CLI also provides a set of entrypoints to help building ANTA content. We call it `debug` and it provides different options:
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` entrypoint and offers the following options:

- Run a command on a device from your inventory and expose the result.
- Run a templated command on a device from your inventory and expose the result.
- Executing a command on a device from your inventory and revealing the result.
- Running a templated command on a device from your inventory and revealing the result.

Both are extremly useful to build your tests since you have visual access to the output you receive from the eAPI. It also help extracting output content to be used by the unit tests, as described in our [contribution guide](../contribution.md).
These tools are especially helpful in building your tests, as they give you visual access to the output you receive from the eAPI. They also facilitate the extraction of output content for use in unit tests, as described in our [contribution guide](../contribution.md).

!!! note "ANTA Inventory"
Because `debug` is based on a device from your inventory, you MUST use a valid [ANTA Inventory](../usage-inventory-catalog.md#create-an-inventory-file).
!!! 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).

## Get the result of an EOS command
## Executing an EOS command

To run a command, you can leverage the `run-cmd` entrypoint with the following options:
You can use the `run-cmd` entrypoint to run a command, which includes the following options:

### Command overview

```bash
$ anta debug run-cmd --help
Expand All @@ -29,7 +31,9 @@ Options:
--help Show this message and exit.
```

In practice, this command is very simple to use. Here is an example using `show interfaces description` with a `JSON` format:
### Example

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

```bash
anta debug run-cmd --command "show interfaces description" --device DC1-SPINE1
Expand All @@ -46,9 +50,11 @@ Run command show interfaces description on DC1-SPINE1
}
```

## Get the result of an EOS command using templates
## 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.

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 followed by a list of arguments (key followed by a value) to build a dictionary used as template parameters:
### Command overview

```bash
$ anta debug run-template --help
Expand All @@ -71,7 +77,9 @@ Options:
--help Show this message and exit.
```

Here is `run-template` in action using `show vlan {vlan_id}` with a `JSON` format:
### 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
Expand All @@ -92,9 +100,11 @@ Run templated command 'show vlan {vlan_id}' with {'vlan_id': '10'} on DC1-LEAF1A
'sourceDetail': ''
}
```
!!! warning "Multiple arguments"
!!! 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'}
Expand Down
177 changes: 122 additions & 55 deletions docs/cli/exec.md
View file
Original file line number Diff line number Diff line change
@@ -1,62 +1,131 @@
# Execute commands on devices
# Executing Commands on Devices

ANTA CLI also provides a set of entrypoints to execute commands remotely on EOS devices.
ANTA CLI incorporates a set of entrypoints to facilitate remote command execution on EOS devices.

### EXEC Command overview
```bash
anta exec --help
Usage: anta exec [OPTIONS] COMMAND [ARGS]...

Execute commands to inventory devices

Options:
--help Show this message and exit.

Commands:
clear-counters Clear counter statistics on EOS devices
collect-tech-support Collect scheduled tech-support from EOS devices
snapshot Collect commands output from devices in inventory
```

## Clear interfaces counters

This command clear interfaces counters on EOS devices defined in your inventory
This command clears interface counters on EOS devices specified in your inventory.

### Command overview

```bash
$ anta exec clear-counters --help
anta exec clear-counters --help
Usage: anta exec clear-counters [OPTIONS]

Clear counter statistics on EOS devices

Options:
-t, --tags TEXT List of tags using comma as separator:
tag1,tag2,tag3
--log-level, --log [debug|info|warning|critical]
Logging level of the command
--help Show this message and exit.
-t, --tags TEXT List of tags using comma as separator: tag1,tag2,tag3
--help Show this message and exit.
```

### Example

```bash
anta exec clear-counters --tags SPINE
[20:19:13] INFO Connecting to devices... utils.py:43
INFO Clearing counters on remote devices... utils.py:46
INFO Cleared counters on DC1-SPINE2 (cEOSLab) utils.py:41
INFO Cleared counters on DC2-SPINE1 (cEOSLab) utils.py:41
INFO Cleared counters on DC1-SPINE1 (cEOSLab) utils.py:41
INFO Cleared counters on DC2-SPINE2 (cEOSLab)
```
## Collect a set of commands

This command collects all commands you defined in a catalog. It can be either `json` or `text`.
This command collects all the commands you've specified in a catalog, which can be in either `json` or `text` format.

### Command overview

```bash
$ anta exec snapshot --help
anta exec snapshot --help
Usage: anta exec snapshot [OPTIONS]

Collect commands output from devices in inventory

Options:
-t, --tags TEXT List of tags using comma as separator:
tag1,tag2,tag3
-c, --commands-list PATH File with list of commands to grab [env
var: ANTA_EXEC_SNAPSHOT_COMMANDS_LIST]
-outut, -o, --output-directory PATH
Path where to save commands output [env
var: ANTA_EXEC_SNAPSHOT_OUTPUT_DIRECTORY]
--log-level, --log [debug|info|warning|critical]
Logging level of the command
--help Show this message and exit.
-t, --tags TEXT List of tags using comma as separator:
tag1,tag2,tag3
-c, --commands-list FILE File with list of commands to collect [env var:
ANTA_EXEC_SNAPSHOT_COMMANDS_LIST; required]
-o, --output DIRECTORY Directory to save commands output. Will have a
suffix with the format _YEAR-MONTH-DAY_HOUR-
MINUTES-SECONDS' [env var:
ANTA_EXEC_SNAPSHOT_OUTPUT; default: anta_snapshot]
--help Show this message and exit.
```
And structure of your catalog file should be:
Your catalog file should follow this structure:
```yaml
---
json_format:
- show version
text_format:
- show agent logs crash
- show bfd peers
- show bgp evpn
```
### Example
```bash
anta exec snapshot --tags SPINE --commands-list ./commands.yaml --output ./
[20:25:15] INFO Connecting to devices... utils.py:78
INFO Collecting commands from remote devices utils.py:81
INFO Collected command 'show version' from device DC2-SPINE1 (cEOSLab) utils.py:76
INFO Collected command 'show version' from device DC2-SPINE2 (cEOSLab) utils.py:76
INFO Collected command 'show version' from device DC1-SPINE1 (cEOSLab) utils.py:76
INFO Collected command 'show version' from device DC1-SPINE2 (cEOSLab) utils.py:76
[20:25:16] INFO Collected command 'show bfd peers' from device DC2-SPINE2 (cEOSLab) utils.py:76
INFO Collected command 'show bfd peers' from device DC2-SPINE1 (cEOSLab) utils.py:76
INFO Collected command 'show bfd peers' from device DC1-SPINE1 (cEOSLab) utils.py:76
INFO Collected command 'show bfd peers' from device DC1-SPINE2 (cEOSLab)
```
The results of the executed commands will be stored in the output directory specified during command execution:
```bash
tree _2023-07-14_20_25_15
_2023-07-14_20_25_15
├── DC1-SPINE1
│   ├── json
│   │   └── show version.json
│   └── text
│   └── show bfd peers.log
├── DC1-SPINE2
│   ├── json
│   │   └── show version.json
│   └── text
│   └── show bfd peers.log
├── DC2-SPINE1
│   ├── json
│   │   └── show version.json
│   └── text
│   └── show bfd peers.log
└── DC2-SPINE2
├── json
│   └── show version.json
└── text
└── show bfd peers.log
12 directories, 8 files
```
## Get Scheduled tech-support
EOS comes with a feature that generates tech-support archive every 1 hour by default and save this archive under `/mnt/flash/schedule/tech-support`
EOS offers a feature that automatically creates a tech-support archive every hour by default. These archives are stored under `/mnt/flash/schedule/tech-support`.
```eos
leaf1#show schedule summary
Expand All @@ -70,46 +139,43 @@ tech-support now 08:37 60 30 100
leaf1#bash ls /mnt/flash/schedule/tech-support
leaf1_tech-support_2023-03-09.1337.log.gz leaf1_tech-support_2023-03-10.0837.log.gz leaf1_tech-support_2023-03-11.0337.log.gz ...
leaf1_tech-support_2023-03-09.1337.log.gz leaf1_tech-support_2023-03-10.0837.log.gz leaf1_tech-support_2023-03-11.0337.log.gz
```
As it can be useful for an NRFU to save a very complete state report before a go live, ANTA has implemented a CLI that retrieves these files very easily:
For Network Readiness for Use (NRFU) tests and to keep a comprehensive report of the system state before going live, ANTA provides a command-line interface that efficiently retrieves these files.
```bash
❯ anta exec collect-tech-support --help
### Command overview
```bash
anta exec collect-tech-support --help
Usage: anta exec collect-tech-support [OPTIONS]
Collect scheduled tech-support from eos devices.
Collect scheduled tech-support from EOS devices
Options:
-o, --output PATH Path for tests catalog [default: ./tech-
support]
-ssh, --ssh-port INTEGER SSH port to use for connection [default:
22]
--insecure / --secure Disable SSH Host Key validation [default:
secure]
--latest INTEGER Number of scheduled show-tech to retrieve
--configure / --not-configure Ensure device has 'aaa authorization exec
default local' configured (required for SCP)
[default: not-configure]
-t, --tags TEXT List of tags using coma as separator:
tag1,tag2,tag3
--log-level, --log [debug|info|warning|critical]
Logging level of the command [default:
info]
--help Show this message and exit.
-o, --output PATH Path for tests catalog [default: ./tech-
support]
--latest INTEGER Number of scheduled show-tech to retrieve
--configure / --not-configure Ensure device has 'aaa authorization exec
default local' configured (required for SCP)
[default: not-configure]
-t, --tags TEXT List of tags using comma as separator:
tag1,tag2,tag3
--help Show this message and exit.
```
When you run this command, it will retrieve tech-support files and download it locally in a folder and a subfolder per device.
You can change the default output folder with the `--output` option.
ANTA download files from the devices using SCP, all SSH Host Key devices must be trusted prior to run the command, otherwise use the `--insecure` option.
In order to use SCP with EOS, the configuration `aaa authorization exec default local` must be present on the devices.
By default, ANTA will not configure this automatically, unless `--configure` is specified.
It is possible to retrieve only the latest tech-support files using the `--latest` option.
When executed, this command fetches tech-support files and downloads them locally into a device-specific subfolder within the designated folder. You can specify the output folder with the `--output` option.
ANTA uses SCP to download files from devices; ensure that all SSH Host Keys are trusted before running the command. Use the `anta --insecure` option if they are not.
The configuration `aaa authorization exec default local` must be enabled on devices for SCP to function. ANTA won't automatically configure this unless `--configure` is specified.

The `--latest` option allows retrieval of a specific number of the most recent tech-support files.

### Example

```bash
❯ anta exec collect-tech-support --insecure
anta --insecure exec collect-tech-support
[15:27:19] INFO Connecting to devices...
INFO Copying '/mnt/flash/schedule/tech-support/spine1_tech-support_2023-06-09.1315.log.gz' from device spine1 to 'tech-support/spine1' locally
INFO Copying '/mnt/flash/schedule/tech-support/leaf3_tech-support_2023-06-09.1315.log.gz' from device leaf3 to 'tech-support/leaf3' locally
Expand All @@ -125,10 +191,10 @@ INFO Collected 1 scheduled tech-support from leaf1
INFO Collected 1 scheduled tech-support from leaf4
```

The output folder will look like this:
The output folder structure is as follows:

```bash
❯ tree tech-support/
tree tech-support/
tech-support/
├── leaf1
│   └── leaf1_tech-support_2023-06-09.1315.log.gz
Expand All @@ -145,3 +211,4 @@ tech-support/
6 directories, 6 files
```
Each device has its own subdirectory containing the collected tech-support files.
4 changes: 2 additions & 2 deletions docs/cli/get-inventory-information.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ Tags found:
* note that tag all has been added by anta
```

!!! note Default all tag
!!! note
Even if you haven't explicitly configured the `all` tag in your inventory, it's automatically added. This default tag allows you to execute commands on all devices in your inventory when you don't specify any particular tag.

## List devices in inventory
Expand All @@ -116,7 +116,7 @@ Options:
```


!!! tip Offline information only
!!! tip
In its default mode, `anta get inventory` provides only information that doesn't rely on a device connection. If you're interested in obtaining connection-dependent details, like the hardware model, please use the `--connected` option.

### Example
Expand Down
26 changes: 14 additions & 12 deletions docs/cli/inv-from-cvp.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
# Create inventory from CloudVision
# Create an Inventory from CloudVision

In a large setup, it can be useful to create your inventory based on CloudVision inventory.
In large setups, it might be beneficial to construct your inventory based on CloudVision. The `from-cvp` entrypoint of the `get` command enables you to create an ANTA inventory from CloudVision.

### Command overview

```bash
$ anta get from-cvp
anta get from-cvp --help
Usage: anta get from-cvp [OPTIONS]

Build ANTA inventory from Cloudvision

Options:
-ip, --cvp-ip TEXT CVP IP Address
-u, --cvp-username TEXT CVP Username
-p, --cvp-password TEXT CVP Password / token
-ip, --cvp-ip TEXT CVP IP Address [required]
-u, --cvp-username TEXT CVP Username [required]
-p, --cvp-password TEXT CVP Password / token [required]
-c, --cvp-container TEXT Container where devices are configured
-d, --inventory-directory PATH Path to save inventory file
--log-level, --log [debug|info|warning|critical]
Logging level of the command
--help Show this message and exit.
```

Output is an inventory with the name of the container added as a tag for the host:
The output is an inventory where the name of the container is added as a tag for each host:

```yaml
anta_inventory:
Expand All @@ -34,10 +34,12 @@ anta_inventory:
- pod2
```
!!! warning Container lookup is not recursive
Current implementation only takes devices directly attached to a specific container when using cli with `--cvp-container` option.
!!! warning
The current implementation only considers devices directly attached to a specific container when using the `--cvp-container` option.

### Creating an inventory from multiple containers

If you want to build an inventory based on multiple containers, you can use a bash command as shown below and then manually concatenate files to create a single inventory file.
If you need to create an inventory from multiple containers, you can use a bash command and then manually concatenate files to create a single inventory file:

```bash
$ for container in pod01 pod02 spines; do anta get from-cvp -ip <cvp-ip> -u cvpadmin -p cvpadmin -c $container -d test-inventory; done
Expand Down
Loading

0 comments on commit 61618e2

Please sign in to comment.