Usage & Arguments¶
There are two primary methods of invoking the functionalities provided by
running directly via the command-line executable
kleenex. This mode allows for independent orchestration & cleaning of your testbed topology, and optionally outputs a resulting testbed YAML file.
Best suited for one-shot preparation of a testbed for script development purposes.
- Easypy Integration
running Kleenex module and functionality under a Easypy plugin model. This orchestrates and cleans your testbed before the job run, and tears it down afterwards, requiring the use of Easypy - Runtime Environment.
Best suited for sanity/regression (official) executions where standard environments, reporting & log archiving is required.
Kleenex is run under decoupled mode when launched using the
command-line executable. Under this mode, the user is given absolute control
over the execution environment, and Kleenex will simply ready-up the testbed.
This mode is great for:
preparing a testbed for script development purposes, eg, developing, debugging and re-running scripts without reloading/re-orchestrating testbed devices.
cleaning/recovering testbed devices to an initial state independent of any script run.
The following is a list of default behaviors during decoupled execution:
logs all outputs to a time-stamped directory under
if bringing up a dynamic topology, keeps the topology up and running, and tears it down only when the user provides
# Example # ------- # using kleenex to clean a physical testbed topology # (using tclclean implementation for device image loading) bash$ kleenex -testbed_file physical_testbed.yaml -clean_file clean.yaml
The unique feature of running under decoupled model of execution is the ability
to specify an orchestrator using
-orchestrator argument and any orchestrator
related information through its command-line arguments without having to go
through a clean file.
The content of the YAML file shown above follows. Note the use of Testbed File Markups in the clean YAML file.
# Example # ------- # # content of the YAML files above --- # clean.yaml cleaners: # This means to use the cleaner class `PyatsDeviceClean` PyatsDeviceClean: # The module is where the cleaner class above can be found module: genie.libs.clean devices: [r1] devices: r1: images: - /path/to/6500-test-image.bin
# Typical Kleenex files Structure # ------------------------------- # base -> cwd or directory specified | -> via -logdir CLI argument |-- Kleenex_2019Mar04_10:41:19.026530 -> kleenex logging directory . |-- Kleenex.log -> Top level clean log . |-- Kleenex.device_1.log -> Device-specific clean log . |-- Kleenex.device_2.log -> Device-specific clean log . |-- Kleenex.device_3.log -> Device-specific clean log |-- env.txt -> environment debug information
The following is a list of typical files generated by the standalone Kleenex tool and their corresponding descriptions:
Top-level clean log
Clean log: one per device that is cleaned.
Contents of the
-testbed-file, if specified by the user.
Contents of the
-clean_file, if specified by the user.
A dump of environment variables and cli args of this Kleenex run.
All clean result details are included in the plugins section of the results.json file. Contains details on each device that was cleaned and any optional clean steps for each device.
Invoking Kleenex as part of a Easypy job run is called Easypy execution mode. In this mode, all environment handling and control is set by the Easypy launcher, and Kleenex is simply run as as a plugin, before and after the job & its tasks runs:
provision & clean the testbed before job and/or task run
teardown the testbed when everything finishes, or when errors are encountered
store all logs inside the Easypy runinfo archive
Easypy execution is the typical way of provisioning & cleaning testbeds before official test runs in sanity/regression shops.
# Example # ------- # using kleenex in pyats to clean a physical testbed topology # (using tclclean implementation for device image loading). bash$ pyats run job myjob.py --testbed-file physical_testbed.yaml\ --clean-file physical_testbed_clean.yaml\ --invoke-clean
Clean is only invoked when the
--invoke-clean parameter is specified.
Kleenex accepts a number of standard arguments. Most of them can be provided as command line arguments to both decoupled & easypy execution models, with some exceptions.
display help information
testbed YAML file to load.
YAML file(s) containing clean configuration details
list of devices to clean
space separated images per device with format device:/path/to/image.bin
space separated images per OS with format os:/path/to/image.bin
space separated images per group with format group:/path/to/image.bin
space separated images per platform with format platform:/path/to/image.bin
kleenex module loglevel
directory to save logs to
disable sending email on abort
Run kleenex in debug mode (synchronous clean, pdb on error)
used under command-line to provide help information w.r.t. available command line arguments and how to use them.
bash$ kleenex -help
specifies the topology Testbed File to load. This informs Kleenex which actual testbed to work with.
bash$ kleenex -testbed_file /path/to/my/testbed.yaml
specifies the YAML-formatted Clean File or files describing how the devices in the topology are to be brought up and/or cleaned. When multiple files are provided, they are handled in the order provided, overriding any shared values from the previous files. For more information on how the contents of this file is used, refer to its documentation.
bash$ kleenex -testbed_file /path/to/my/testbed.yaml\ -clean_file /path/to/my/clean.yaml
specifies the list of devices to clean. If not specified, defaults to cleaning all devices specified in the clean file that are also present in the testbed file.
bash$ pyats run job jobfile.py --testbed-file /path/to/my/testbed.yaml\ --clean-file /path/to/my/clean.yaml\ --clean-devices device_a device_b device_c\ --invoke-clean
Groups of devices to be sequentially cleaned may be specified via nested list format. In the following example, device_a, device_b and device_c are cleaned in parallel, and only once complete are device_d and device_e cleaned in parallel.
bash$ pyats run job jobfile.py --testbed-file /path/to/my/testbed.yaml\ --clean-file /path/to/my/clean.yaml\ --clean-devices "[[device_a, device_b, device_c], [device_d, device_e]]"\ --invoke-clean
specifies images to be used for clean per device. See the following for more details about the expected format of the images and the precedence when images are provided through a combination of
bash$ pyats run job jobfile.py --testbed-file /path/to/my/testbed.yaml\ --clean-file /path/to/my/clean.yaml --invoke-clean --clean-device-image PE1:/path/to/clean_image.bin
specifies images to be used for clean per OS. Uses same format as
bash$ pyats run job jobfile.py --testbed-file /path/to/my/testbed.yaml\ --clean-file /path/to/my/clean.yaml --invoke-clean --clean-os-image iosxe:/path/to/clean_image.bin
specifies images to be used for clean per group. Uses same format as
bash$ pyats run job jobfile.py --testbed-file /path/to/my/testbed.yaml\ --clean-file /path/to/my/clean.yaml --invoke-clean --clean-group-image group1:/path/to/clean_image.bin
specifies images to be used for clean per platform. Uses same format as
bash$ pyats run job jobfile.py --testbed-file /path/to/my/testbed.yaml\ --clean-file /path/to/my/clean.yaml --invoke-clean --clean-platform-image n9k:/path/to/clean_image.bin
specifies the logging level for Kleenex. Use this to increase or decrease Kleenex module’s log output level for debugging purposes. May be specified in UPPERCASE or lowercase.
bash$ kleenex -testbed_file /path/to/my/testbed.yaml\ -clean_file /path/to/my/clean.yaml\ -loglevel DEBUG
specifies the logging directory for Kleenex. In easypy mode, this defaults to the Easypy runinfo directory. In decoupled mode, this defaults to the current working directory.
bash$ kleenex -testbed_file /path/to/my/testbed.yaml\ -clean_file /path/to/my/clean.yaml\ -logdir /tmp
when defaulting to current working directory, a folder named
Kleenex_%Y%b%d_%H:%M:%Sis created per run.
disables sending email to user when abort/error is encountered.
bash$ kleenex -testbed_file /path/to/my/testbed.yaml\ -clean_file /path/to/my/clean.yaml\ -no_mail
put kleenex into debug mode. May also be specified with the
-pdbcommand-line parameter. In debug mode, kleenex runs its cleaners in series instead of in parallel. If a cleaner worker throws an exception, an interactive debugger is started at the point of failure.
bash$ kleenex -testbed_file /path/to/my/testbed.yaml\ -clean_file /path/to/my/clean.yaml\ -debug