Usage & Arguments¶

There are two primary methods of invoking the functionalities provided by kleenex module:

Decoupled

running directly via the command-line executable pyats clean. 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.

Decoupled Execution¶

Kleenex is run under decoupled mode when launched using the pyats clean 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 pwd

if bringing up a dynamic topology, keeps the topology up and running, and tears it down only when the user provides Ctrl-C input.

# Example
# -------

# using kleenex to clean a physical testbed topology
bash$ pyats clean --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

File Structure¶

# 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

Files¶

The following is a list of typical files generated by the standalone Kleenex tool and their corresponding descriptions:

Kleenex.log: Top-level clean log
Kleenex.<device_name>.log: Clean log: one per device that is cleaned.
testbed.static.yaml: Contents of the --testbed-file, if specified by the user.
testbed.clean.yaml: Contents of the --clean-file, if specified by the user.
env.txt: A dump of environment variables and cli args of this Kleenex run.
results.json: 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.

Easypy Integration¶

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 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
bash$ pyats run job myjob.py --testbed-file physical_testbed.yaml\
                             --clean-file physical_testbed_clean.yaml\
                             --invoke-clean

Note

Clean is only invoked when the --invoke-clean parameter is specified.

Standard Arguments¶

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.

pyATS Clean(Kleenex) Standard Arguments¶
Argument	Description
`--help`	display help information
`--testbed-file`	testbed YAML file to load.
`--clean-file`	YAML file(s) containing clean configuration details
`--clean-devices`	list of devices to clean
`--clean-device_image`	space separated images per device with format device:/path/to/image.bin
`--clean-os-image`	space separated images per OS with format os:/path/to/image.bin
`--clean-group-image`	space separated images per group with format group:/path/to/image.bin
`--clean-platform-image`	space separated images per platform with format platform:/path/to/image.bin
`--loglevel`	kleenex module loglevel
`--logdir`	directory to save logs to
`--no-mail`	disable sending email on abort
`--debug`	Run kleenex in debug mode (synchronous clean, pdb on error)

--help

used under command-line to provide help information w.r.t. available command line arguments and how to use them.

bash$ pyats clean -help

--testbed-file

specifies the topology Testbed File to load. This informs Kleenex which actual testbed to work with.

bash$ pyats clean -testbed_file /path/to/my/testbed.yaml

--clean-file

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$ pyats clean --testbed-file /path/to/my/testbed.yaml\
              --clean-file /path/to/my/clean.yaml

--clean-devices

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

--clean-device-image

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 --clean-device-image, --clean-os-image, --clean-group-image and --clean-platform-image.

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

--clean-os-image

specifies images to be used for clean per OS. Uses same format as --clean-device-image.

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

--clean-group-image

specifies images to be used for clean per group. Uses same format as --clean-device-image.

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

--clean-platform-image

specifies images to be used for clean per platform. Uses same format as --clean-device-image.

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

--loglevel

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$ pyats clean --testbed-file /path/to/my/testbed.yaml\
                  --clean-file /path/to/my/clean.yaml\
                  --loglevel DEBUG

--logdir

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$ pyats clean --testbed-file /path/to/my/testbed.yaml\
                  --clean-file /path/to/my/clean.yaml\
                  --logdir /tmp

Note

when defaulting to current working directory, a folder named Kleenex_%Y%b%d_%H:%M:%S is created per run.

--no-mail

disables sending email to user when abort/error is encountered.

bash$ pyats clean --testbed-file /path/to/my/testbed.yaml\
                  --clean-file /path/to/my/clean.yaml\
                  --no-mail

--debug

put kleenex into debug mode. May also be specified with the -pdb command-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$ pyats clean --testbed-file /path/to/my/testbed.yaml\
                  --clean-file /path/to/my/clean.yaml\
                  --debug