Appendix A. Chaos Toolkit Reference

The Chaos Toolkit is at its heart a simple CLI that introduces the chaos command.

The Default Chaos Commands

If you execute the chaos --help command once you’ve installed the Chaos Toolkit (see Chapter 4), you will see a list of the sub-commands that are supported:

(chaostk) $ chaos --help
Usage: chaos [OPTIONS] COMMAND [ARGS]...

Options:
  --version           Show the version and exit.
  --verbose           Display debug level traces.
  --no-version-check  Do not search for an updated version of the
                      chaostoolkit.
  --change-dir TEXT   Change directory before running experiment.
  --no-log-file       Disable logging to file entirely.
  --log-file TEXT     File path where to write the command's log.  [default:
                      chaostoolkit.log]
  --settings TEXT     Path to the settings file.  [default:
                      /Users/russellmiles/.chaostoolkit/settings.yaml]
  --help              Show this message and exit.

Commands:
  discover  Discover capabilities and experiments.
  info      Display information about the Chaos Toolkit environment.
  init      Initialize a new experiment from discovered capabilities.
  run       Run the experiment loaded from SOURCE, either a local file or a...
  validate  Validate the experiment at PATH.

This is the default set of sub-commands; you might see more than are listed here, especially if you’ve installed the reporting plug-in (see “Creating and Sharing Human-Readable Chaos Experiment Reports”). They represent a workflow that goes a little beyond the chaos run command you’ve used throughout this book (see Figure A-1).

An image of the workflow for the discover, init, validate and run sub-commands.
Figure A-1. The workflow for discover, init, validate, and run

Exploring the Options

You can also inspect all the options for the sub-commands by appending them with --help (for example, chaos discover --help).

You already know that you can use the chaos run command to execute your JSON or YAML format experiments. That works fine, and it’s easily the most common command to use. The other commands are there to help you author your experiments, so let’s take a deeper look at those now.

Discovering What’s Possible with the chaos discover Command

One starting point when writing a new Chaos Toolkit experiment is the discover command. discover allows you to point your toolkit at an environment and have the toolkit try to discover what is there so that the information retrieved can be used to inform the generation of future experiments (see “Authoring a New Experiment with the chaos init Command”).

To show this in action, here’s an example of using the discover command to inspect a Kubernetes target system and discover what is present:

(chaostk) $ chaos discover chaostoolkit-kubernetes
[2019-05-16 14:38:35 INFO] Attempting to download and install package \
                           'chaostoolkit-kubernetes'
[2019-05-16 14:38:36 INFO] Package downloaded and
                           installed in current environment
[2019-05-16 14:38:37 INFO] Discovering capabilities from chaostoolkit-kubernetes
[2019-05-16 14:38:37 INFO] Searching for actions
[2019-05-16 14:38:37 INFO] Searching for probes
[2019-05-16 14:38:37 INFO] Searching for actions
[2019-05-16 14:38:37 INFO] Searching for probes
[2019-05-16 14:38:37 INFO] Searching for actions
[2019-05-16 14:38:37 INFO] Discovery outcome saved in ./discovery.json

When executing the chaos discover command, you must supply the name of an extension to the Chaos Toolkit (in this case the Kubernetes extension chaostoolkit-kubernetes). This extension must in turn supply a discover function in its code, as it is this call that is used by the Chaos Toolkit. You can see an implementation of the discover function in the chaostoolkit-kubernetes driver:

def discover(discover_system: bool = True) -> Discovery:
    """
    Discover Kubernetes capabilities offered by this extension.
    """
    logger.info("Discovering capabilities from chaostoolkit-kubernetes")

    discovery = initialize_discovery_result(
        "chaostoolkit-kubernetes", __version__, "kubernetes")
    discovery["activities"].extend(load_exported_activities())
    return discovery

Nothing to Discover

Some extensions do not implement a discover function and thus will not return anything special when you refer to them with chaos discover.

When you execute chaos discover chaostoolkit-kubernetes, the Chaos Toolkit first checks whether the chaostoolkit-kubernetes Python module has been installed. If it hasn’t, the toolkit will go ahead and attempt to install it.

Then the Chaos Toolkit will use the discover function to explore what is available in your currently configured Kubernetes environment. As you can see from the command output, the discover command constructs a view of your target system that can include:

Activities

The probes or actions the extension can helpfully provide to work against the target system

System information

A collection of information about the target system that can be helpful later when creating your experiments

All of this information is returned in a file that is called discovery.json by default. You can specify a different filename for your discovered information by passing the --discovery-path parameter to the chaos discover command.

You can open up your new discovery.json file and see the sorts of information returned for a given execution of chaos discover, but the real power of that file is that it is now used by the next step in the workflow: chaos init.