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).
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:
defdiscover(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())returndiscovery
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.
Authoring a New Experiment with the chaos init Command
The chaos discover command produces raw information about the system that you are targeting with your soon-to-be-written chaos experiment. With the discovery.json file in hand, you can now use the chaos init command to initialize a new experiment based on that discovered information:
(chaostk) $ chaos init You are about to create an experiment. This wizard will walk you through each step so that you can build the best experiment for your needs. An experiment is made up of three elements: - a steady-state hypothesis [OPTIONAL] - an experimental method - a set of rollback activities [OPTIONAL] Only the method is required. Also your experiment will not run unless you define at least one activity (probe or action) within it Experiment's title: ...
The information provided from discovery.json is used by the chaos init command to present a wizard-style set of questions that talk you through the initial version of a new experiment. When you’re finished, a new experiment.json file is generated for you to refine and execute.
Checking Your Experiment with the chaos validate Command
When you execute an experiment with chaos run, your experiment format is validated before any steps of the experiment are run. You can turn off this validation using the --no-validation switch, but most of the time it is still a valuable step.
When you’re constructing a new experiment from scratch using the chaos discover and chaos init workflow, it can be useful to validate your experiment’s format without the experiment being executed. You can achieve this with the chaos run command by providing the --dry switch, but it’s cleaner to use the chaos validate command instead.
The combination of chaos discover, chaos init, and chaos validate exists to ease your experiment-creation life. With these tools at hand, you can quickly create JSON and YAML experiments for your Chaos Toolkit to execute.
Extending the Chaos Commands with Plug-ins
You can also extend the behavior of the chaos command using Chaos Toolkit plug-ins. This is great for when you want to introduce your own custom sub-commands beyond the out-of-the-box ones.
One example that you’ve already seen is the chaostoolkit-reporting plug-in. The Chaos Toolkit uses the click Python library to manage its commands, and the chaostoolkit-reporting plug-in extends the toolkit with the chaos report sub-command by implementing that command in a report method:
@click.command()@click.option('--export-format',default="markdown",help='Format to export the report to: html, markdown, pdf.')@click.argument('journal',type=click.Path(exists=True),nargs=-1)@click.argument('report',type=click.Path(exists=False),nargs=1)defreport(export_format:str="markdown",journal:str="journal.json",report:str="report.md"):"""Generate a report from the run journal(s)."""header=generate_report_header(journal,export_format)report_path=reportreports=[]iflen(journal)==1andnotos.path.isfile(journal[0]):journal=glob(journal)forjournalinjournal:reports.append(generate_report(journal,export_format))save_report(header,reports,report_path,export_format)click.echo("Report generated as '{f}'".format(f=report))
You can also add Chaos Toolkit CLI plug-in extensions to your own custom extension projects by implementing your own commands this way (see Chapter 8).