From 7763cc454d686d51bf2e0ccc1f2ccf7d62a0d625 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 14 Apr 2024 10:36:44 +0200 Subject: Merging upstream version 0.14.0. Signed-off-by: Daniel Baumann --- docs/cli/debug.md | 39 ++++++++-------- docs/cli/exec.md | 54 +++++++++++------------ docs/cli/get-inventory-information.md | 31 +++++++------ docs/cli/inv-from-ansible.md | 2 +- docs/cli/nrfu.md | 83 ++++++++--------------------------- docs/cli/overview.md | 8 ++-- 6 files changed, 85 insertions(+), 132 deletions(-) (limited to 'docs/cli') diff --git a/docs/cli/debug.md b/docs/cli/debug.md index 1743c7a..db5f496 100644 --- a/docs/cli/debug.md +++ b/docs/cli/debug.md @@ -23,10 +23,9 @@ You can use the `run-cmd` entrypoint to run a command, which includes the follow ### Command overview ```bash -$ anta debug run-cmd --help Usage: anta debug run-cmd [OPTIONS] - Run arbitrary command to an ANTA device + Run arbitrary command to an ANTA device. Options: -u, --username TEXT Username to connect to EOS [env var: @@ -44,16 +43,17 @@ Options: 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: + --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: + --disable-cache Disable cache globally. [env var: ANTA_DISABLE_CACHE] - -i, --inventory FILE Path to the inventory YAML file [env var: + -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] + --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 @@ -90,15 +90,15 @@ The `run-template` entrypoint allows the user to provide an [`f-string`](https:/ ### 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: + used as template parameters. - anta debug run-template -d leaf1a -t 'show vlan {vlan_id}' vlan_id 1 + 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: @@ -116,16 +116,17 @@ Options: 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: + --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: + --disable-cache Disable cache globally. [env var: ANTA_DISABLE_CACHE] - -i, --inventory FILE Path to the inventory YAML file [env var: + -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] + --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 diff --git a/docs/cli/exec.md b/docs/cli/exec.md index fe39c12..061a19e 100644 --- a/docs/cli/exec.md +++ b/docs/cli/exec.md @@ -31,10 +31,9 @@ This command clears interface counters on EOS devices specified in your inventor ### Command overview ```bash -anta exec clear-counters --help Usage: anta exec clear-counters [OPTIONS] - Clear counter statistics on EOS devices + Clear counter statistics on EOS devices. Options: -u, --username TEXT Username to connect to EOS [env var: ANTA_USERNAME; @@ -50,16 +49,16 @@ Options: 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: + --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: + --disable-cache Disable cache globally. [env var: ANTA_DISABLE_CACHE] - -i, --inventory FILE Path to the inventory YAML file [env var: + -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] + --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3. [env var: ANTA_TAGS] --help Show this message and exit. ``` @@ -84,10 +83,9 @@ This command collects all the commands specified in a commands-list file, which ### Command overview ```bash -anta exec snapshot --help Usage: anta exec snapshot [OPTIONS] - Collect commands output from devices in inventory + Collect commands output from devices in inventory. Options: -u, --username TEXT Username to connect to EOS [env var: @@ -105,21 +103,22 @@ Options: 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: + --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: + --disable-cache Disable cache globally. [env var: ANTA_DISABLE_CACHE] - -i, --inventory FILE Path to the inventory YAML file [env var: + -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] + --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3. [env var: ANTA_TAGS] -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. [env var: ANTA_EXEC_SNAPSHOT_OUTPUT; default: - anta_snapshot_2023-12-06_09_22_11] + anta_snapshot_2024-04-09_15_56_19] --help Show this message and exit. ``` @@ -203,10 +202,9 @@ For Network Readiness for Use (NRFU) tests and to keep a comprehensive report of ### 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: -u, --username TEXT Username to connect to EOS [env var: ANTA_USERNAME; @@ -222,16 +220,16 @@ Options: 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: + --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: + --disable-cache Disable cache globally. [env var: ANTA_DISABLE_CACHE] - -i, --inventory FILE Path to the inventory YAML file [env var: + -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] + --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3. [env var: ANTA_TAGS] -o, --output PATH Path for test catalog [default: ./tech-support] --latest INTEGER Number of scheduled show-tech to retrieve --configure Ensure devices have 'aaa authorization exec default diff --git a/docs/cli/get-inventory-information.md b/docs/cli/get-inventory-information.md index 70100fe..1831484 100644 --- a/docs/cli/get-inventory-information.md +++ b/docs/cli/get-inventory-information.md @@ -72,7 +72,6 @@ As most of ANTA's commands accommodate tag filtering, this particular command is ### Command overview ```bash -anta get tags --help Usage: anta get tags [OPTIONS] Get list of configured tags in user inventory. @@ -91,16 +90,16 @@ Options: 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: + --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: + --disable-cache Disable cache globally. [env var: ANTA_DISABLE_CACHE] - -i, --inventory FILE Path to the inventory YAML file [env var: + -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] + --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3. [env var: ANTA_TAGS] --help Show this message and exit. ``` @@ -132,7 +131,6 @@ This command will list all devices available in the inventory. Using the `--tags ### Command overview ```bash -anta get inventory --help Usage: anta get inventory [OPTIONS] Show inventory loaded in ANTA. @@ -153,16 +151,17 @@ Options: 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: + --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: + --disable-cache Disable cache globally. [env var: ANTA_DISABLE_CACHE] - -i, --inventory FILE Path to the inventory YAML file [env var: + -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] + --tags TEXT List of tags using comma as separator: + tag1,tag2,tag3. [env var: ANTA_TAGS] --connected / --not-connected Display inventory after connection has been created --help Show this message and exit. diff --git a/docs/cli/inv-from-ansible.md b/docs/cli/inv-from-ansible.md index bb944d4..ebe7da3 100644 --- a/docs/cli/inv-from-ansible.md +++ b/docs/cli/inv-from-ansible.md @@ -39,7 +39,7 @@ anta_inventory: ``` !!! warning - The current implementation only considers devices directly attached to a specific Ansible group and does not support inheritence when using the `--ansible-group` option. + The current implementation only considers devices directly attached to a specific Ansible group and does not support inheritance when using the `--ansible-group` option. By default, if user does not provide `--output` file, anta will save output to configured anta inventory (`anta --inventory`). If the output file has content, anta will ask user to overwrite when running in interactive console. This mechanism can be controlled by triggers in case of CI usage: `--overwrite` to force anta to overwrite file. If not set, anta will exit diff --git a/docs/cli/nrfu.md b/docs/cli/nrfu.md index 6dcc393..7427f62 100644 --- a/docs/cli/nrfu.md +++ b/docs/cli/nrfu.md @@ -13,51 +13,10 @@ ANTA provides a set of commands for performing NRFU tests on devices. These comm - [JSON view](#performing-nrfu-with-json-rendering) - [Custom template view](#performing-nrfu-with-custom-reports) -### NRFU Command overview +## NRFU Command overview ```bash -anta nrfu --help -Usage: anta nrfu [OPTIONS] COMMAND [ARGS]... - - Run NRFU against inventory devices - -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] - -c, --catalog FILE Path to the test catalog YAML file [env var: - ANTA_CATALOG; required] - --ignore-status Always exit with success [env var: - ANTA_NRFU_IGNORE_STATUS] - --ignore-error Only report failures and not errors [env var: - ANTA_NRFU_IGNORE_ERROR] - --help Show this message and exit. - -Commands: - json ANTA command to check network state with JSON result - table ANTA command to check network states with table result - text ANTA command to check network states with text result - tpl-report ANTA command to check network state with templated report +--8<-- "anta_nrfu_help.txt" ``` > `username`, `password`, `enable-password`, `enable`, `timeout` and `insecure` values are the same for all devices @@ -67,7 +26,7 @@ All commands under the `anta nrfu` namespace require a catalog yaml file specifi !!! info Issuing the command `anta nrfu` will run `anta nrfu table` without any option. -## Tag management +### Tag management The `--tags` option can be used to target specific devices in your inventory and run only tests configured with this specific tags from your catalog. The default tag is set to `all` and is implicit. Expected behaviour is provided below: @@ -80,6 +39,14 @@ The `--tags` option can be used to target specific devices in your inventory and !!! info [More examples](tag-management.md) available on this dedicated page. +### Device and test filtering + +Options `--device` and `--test` can be used to target one or multiple devices and/or tests to run in your environment. The options can be repeated. Example: `anta nrfu --device leaf1a --device leaf1b --test VerifyUptime --test VerifyReloadCause`. + +### Hide results + +Option `--hide` can be used to hide test results in the output based on their status. The option can be repeated. Example: `anta nrfu --hide error --hide skipped`. + ## Performing NRFU with text rendering The `text` subcommand provides a straightforward text report for each test executed on all devices in your inventory. @@ -87,25 +54,18 @@ The `text` subcommand provides a straightforward text report for each test execu ### Command overview ```bash -anta nrfu text --help Usage: anta nrfu text [OPTIONS] - ANTA command to check network states with text result + ANTA command to check network states with text result. Options: - -s, --search TEXT Regular expression to search in both name and test - --skip-error Hide tests in errors due to connectivity issue - --help Show this message and exit. + --help Show this message and exit. ``` -The `--search` option permits filtering based on a regular expression pattern in both the hostname and the test name. - -The `--skip-error` option can be used to exclude tests that failed due to connectivity issues or unsupported commands. - ### Example ```bash -anta nrfu text --tags LEAF --search DC1-LEAF1A +anta nrfu --device DC1-LEAF1A text ``` [![anta nrfu text results](../imgs/anta-nrfu-text-output.png){ loading=lazy width="1600" }](../imgs/anta-nrfu-text-output.png) @@ -116,20 +76,15 @@ The `table` command under the `anta nrfu` namespace offers a clear and organized ### Command overview ```bash -anta nrfu table --help Usage: anta nrfu table [OPTIONS] - ANTA command to check network states with table result + ANTA command to check network states with table result. Options: - -d, --device TEXT Show a summary for this device - -t, --test TEXT Show a summary for this test - --group-by [device|test] Group result by test or host. default none + --group-by [device|test] Group result by test or device. --help Show this message and exit. ``` -The `--device` and `--test` options show a summarized view of the test results for a specific host or test case, respectively. - The `--group-by` option show a summarized view of the test results per host or per test. ### Examples @@ -154,12 +109,12 @@ anta nrfu table --group-by test To get more specific information, it is possible to filter on a single device or a single test: ```bash -anta nrfu table --device spine1 +anta nrfu --device spine1 table ``` [![anta nrfu table filter_host_output](../imgs/anta-nrfu-table-filter-host-output.png){ loading=lazy width="1600" }](../imgs/anta-nrfu-table-filter-host-output.png) ```bash -anta nrfu table --test VerifyZeroTouch +anta nrfu --test VerifyZeroTouch table ``` [![anta nrfu table filter_test_output](../imgs/anta-nrfu-table-filter-test-output.png){ loading=lazy width="1600" }](../imgs/anta-nrfu-table-filter-test-output.png) @@ -173,7 +128,7 @@ The JSON rendering command in NRFU testing is useful in generating a JSON output anta nrfu json --help Usage: anta nrfu json [OPTIONS] - ANTA command to check network state with JSON result + ANTA command to check network state with JSON result. Options: -o, --output FILE Path to save report as a file [env var: diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 90e70a5..5e95ff5 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -22,7 +22,7 @@ $ anta --help --8<-- "anta_help.txt" ``` -## ANTA environement variables +## ANTA environment variables Certain parameters are required and can be either passed to the ANTA CLI or set as an environment variable (ENV VAR). @@ -48,10 +48,10 @@ anta nrfu ``` !!! note - All environement variables may not be needed for every commands. - Refer to ` --help` for the comprehensive environment varibles names. + All environment variables may not be needed for every commands. + Refer to ` --help` for the comprehensive environment variables names. -Below are the environement variables usable with the `anta nrfu` command: +Below are the environment variables usable with the `anta nrfu` command: | Variable Name | Purpose | Required | | ------------- | ------- |----------| -- cgit v1.2.3