Chaos Toolkit - Chaos Engineering for Everyone
Purpose
The purpose of this library is to provide the core of the Chaos Toolkit model and functions it needs to render its services.
Features
The library provides the followings features:
-
discover capabilities from extensions Allows you to explore the support from an extension that would help you initialize an experiment against the system this extension targets
-
validate a given experiment syntax The validation looks at various keys in the experiment and raises errors whenever something doesn't look right. As a nice addition, when a probe calls a Python function with arguments, it tries to validate the given argument list matches the signature of the function to apply.
-
run your steady state before and after the method. The former as a gate to decide if the experiment can be executed. The latter to see if the system deviated from normal.
-
run probes and actions declared in an experiment It runs the steps in a experiment method sequentially, applying first steady probes, then actions and finally close probes.
A journal, as a JSON payload, is return of the experiment run.
The library supports running probes and actions defined as Python functions, from importable Python modules, processes and HTTP calls.
-
run experiment's rollbacks when provided
-
Load secrets from the experiments, the environ or vault
-
Provides event notification from Chaos Toolkit flow (although the actual events are published by the CLI itself, not from this library), supported events are:
- on experiment validation: started, failed or completed
- on discovery: started, failed or completed
- on initialization of experiments: started, failed or completed
- on experiment runs: started, failed or completed
For each event, the according payload is part of the event as well as a UTC timestamp.
Install
If you are user of the Chaos Toolkit, you probably do not need to install this package yourself as it comes along with the chaostoolkit cli.
However, should you wish to integrate this library in your own Python code, please install it as usual:
$ pip install -U chaostoolkit-lib
Specific dependencies
In addition to essential dependencies, the package can install a couple of other extra dependencies for specific use-cases. They are not mandatory and the library will warn you if you try to use a feature that requires them.
Vault
If you need Vault support to read secrets from, run the following command:
$ pip install -U chaostoolkit-lib[vault]
To authenticate with Vault, you can either:
- Use a token through the
vault_tokenconfiguration key - Use an AppRole via the
vault_role_id,vault_secret_idpair of configuration keys - Use a service account configured with an appropriate role via the
vault_sa_roleconfiguration key. Thevault_sa_token_path,vault_k8s_mount_point, andvault_secrets_mount_pointconfiguration keys can optionally be specified to point to a location containing a service account token, a different Kubernetes authentication method mount point, or a different secrets mount point, respectively.
JSON Path
If you need JSON Path support for tolerance probes in the hypothesis, also run the following command:
$ pip install -U chaostoolkit-lib[jsonpath]
Contribute
Contributors to this project are welcome as this is an open-source effort that seeks discussions and continuous improvement.
From a code perspective, if you wish to contribute, you will need to run a
Python 3.6+ environment. Please, fork this project, write unit tests to cover
the proposed changes, implement the changes, ensure they meet the formatting
standards set out by black, flake8, and isort, add an entry into
CHANGELOG.md, and then raise a PR to the repository for review.
Please refer to the formatting section for more information on the formatting standards.
The Chaos Toolkit projects require all contributors must sign a Developer Certificate of Origin on each commit they would like to merge into the master branch of the repository. Please, make sure you can abide by the rules of the DCO before submitting a PR.
Develop
If you wish to develop on this project, make sure to install the development dependencies. To do so, first install pdm.
$ pdm install --dev
Now, you can edit the files and they will be automatically be seen by your
environment, even when running from the chaos command locally.
Test
To run the tests for the project execute the following:
$ pdm run test
Formatting and Linting
We use ruff to perform linting and code style.
Before raising a Pull Request, we recommend you run formatting against your code with:
$ pdm run format
This will automatically format any code that doesn't adhere to the formatting standards.
As some things are not picked up by the formatting, we also recommend you run:
$ pdm run lint
To ensure that any unused import statements/strings that are too long, etc. are also picked up.
1 maintainer
Metadata
1 maintainer
Release files for chaostoolkit-lib 1.45.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| chaostoolkit_lib-1.45.1.tar.gz | 86.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| chaostoolkit_lib-1.45.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 148.9 kB
Release files / chaostoolkit_lib-1.45.1.tar.gz
| Download URL | chaostoolkit_lib-1.45.1.tar.gz |
|---|---|
| Size | 86.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f514a6b63e636feb3b2d19a839db182add49bdf83a3bad6c9e8da11feae28f2b
|
|
BLAKE2b-256 checksum How to use checksums |
6bc2ca8767f8bb0c09468c7b78fa45ba56864795ff53ef4352aa7412dd090e38
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency logRelease files / chaostoolkit_lib-1.45.1-py3-none-any.whl
| Download URL | chaostoolkit_lib-1.45.1-py3-none-any.whl |
|---|---|
| Size | 62.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4cfbf9c6a7cbfb5295d56822167f514b0944a85a598e7251de5e47c022e974dd
|
|
BLAKE2b-256 checksum How to use checksums |
3fa94dac05b819b640acf1c028e047f5b415c39602fbac4ce017f52af7ba1824
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 27, 2026.
Transparency log
