Welcome to the Chaos Toolkit driver for Toxiproxy! This extension allows you to setup toxy proxy probes and methods from chaostoolkit by leveraging the toxyproxy http management api.

1. Install the Toxiproxy base client
2. Install the Toxiproxy CLI

This package requires Python 3.5+

To be used from your experiment, this package must be installed in the Python environment where chaostoolkit already lives.

$ pip install -U chaostoolkit-toxiproxy

First, run the Toxiproxy base client locally to create a localhost:8474 host on your computer. Then create a proxy.

Next, to start using the actions and probes all you need to do is add the toxiproxy host with "toxiproxy_host" as the key, and optionally the port with "toxiproxy_port" as the key, to the configuration section in your experiment json. If not provided the port defaults to 8474.

Alternatively, if toxiproxy api is accessible using a reverse proxy, you can use toxiproxy_url setting.

Example using toxiproxy_host in experiment.json

"configuration": {
    "toxiproxy_host" : "10.124.23.183",
    "some_environment_variable": {
      "type": "environment",
      "key": "ENVIRONMENT_VARIABLE"
    }
  },

Example using toxiproxy_url in experiment.json

"configuration": {
    "toxiproxy_url" : "http://mydomain.com:8080/path-to-toxiproxy-api",
    "some_environment_variable": {
      "type": "environment",
      "key": "ENVIRONMENT_VARIABLE"
    }
  },

This extension follows the toxiproxy rules. A proxy is the channel where toxicity can be added. For this reason the extension is broken into proxy management and toxic management.

All actions and probes in the extension are of python type and are used like any other python extension.

Creates a proxy to which toxics can be added. In toxiproxy a listen port of value 0 tells the API to assign a random available port. The value where the proxy is listenting will be attached to the chaostoolkit configuration object as <proxyname>_PORT. Should the creation of the proxy fail, an assertion error is raised stopping all subsequent actions.

Modify the configuration of a given proxy. Useful to change the upstream configiuration. Only arguments supplied result in modification of the proxy.

Disables the proxy, this is useful to simulate a proxied service being down.

Enables a disabled proxy.

Removes the proxy from the system.

Example usage

 "method": [
      {
            "type": "action",
            "name": "setup_toxiproxy_proxy",
            "provider": {
                "type": "python",
                "module": "chaostoxi.proxy.actions",
                "func": "create_proxy",
                "arguments": {
                    "proxy_name": "myproxy",
                    "listen_port" : 6666,
                    "upstream_host" : "10.28.188.118",
                    "upstream_port" : 6040
                }
            },
            "pauses": {
                "after": 1
            }
        }
      ] 

Enable all proxies and remove all active toxics.

Example usage:

"method": [
    {
        "type": "action",
        "name": "reset all proxies",
        "provider": {
            "type": "python",
            "module": "chaostoxi.proxy.actions",
            "func": "reset"
        },
        "pauses": {
            "after": 1
        }
    }
]

Returns True of False if a given proxy exists.

All actions provided by this extension match the types and attributes of toxics.

Allows you to create any of the supported types of toxics with their attributes.

Add a delay to all data going through the proxy using a downstream with a toxicity of 100%.

Limit the bandwith of a downstream connection with a toxicity of 100%.

Generate as downstream delayed TCP close with a toxicity of 100%.

Slices TCP data up into small bits, optionally adding a delay between each sliced "packet" with a toxicity of 100%.

Closes connections when transmitted data after the limit, sets it up as a dowsntream, 100% toxicity.

Deletes the a given toxic.

Example usage:

 "method": [        
      {
            "type": "action",
            "name": "create_latency_toxic",
            "provider": {
                "type": "python",
                "module": "toxiproxy.toxic.actions",
                "func": "create_dowsntream_latency_toxic",
                "arguments": {
                    "for_proxy": "edsproxy",
                    "toxic_name": "latency_toxic",
                    "latency": 5000,
                    "jitter": 200
                }
            },
            "pauses": {
                "after": 1
            }
        }    
 ]

If you wish to contribute more functions to this package, you are more than welcome to do so. Please, fork this project, make your changes following the usual PEP 8 code style, sprinkling with tests and submit a PR for review.

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.

If you wish to develop on this project, make sure to install the development dependencies. But first, create a virtual environment and then install those dependencies.

$ pip install -r requirements-dev.txt -r requirements.txt

Then, point your environment to this directory:

$ python setup.py develop

Now, you can edit the files and they will be automatically be seen by your environment, even when running from the chaos command locally.

To run the unit tests for the project execute the following:

$ pytest

To run the integration tests for the project execute the following:

$ tox