Skip to content

Extension chaostoxi

Version 0.3.1
Repository https://github.com/chaostoolkit-incubator/chaostoolkit-toxiproxy

Build Status Python versions

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.

Install

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

Driver

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

Usage

Configuration

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.

Proxy actions

create_proxy

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.

Argument Description Required Default
proxy_name name for the proxy Yes None
upstream_host ip address of the host to send traffic to Yes None
upstream_port port of the application to send traffic to Yes None
listen_host IP address to bind where toxiproxy listens No 0.0.0.0
listen_port port to listen for requests, 0 means pick random value No 0
enabled Whether to start listening or not No True

modify_proxy

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

Argument Description Required Default
proxy_name name for the proxy Yes None
listen_addres ip:port address to modify No None
upstream_addres ip:port of the upstream No None
enabled Toggle enabled/disabled state No None

disable_proxy

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

Argument Description Required Default
proxy_name name for the proxy to disable Yes None

enable_proxy

Enables a disabled proxy.

Argument Description Required Default
proxy_name name for the proxy to enable Yes None

delete_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
            }
        }
      ] 

reset

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
        }
    }
]

Proxy pobes

proxy_exist

Returns True of False if a given proxy exists.

Argument Description Required Default
proxy_name name for the proxy Yes None

Toxic actions

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

create_toxic

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

Argument Description Required Default
for_proxy name for the proxy to attach the toxy Yes None
toxic_name name for this toxy Yes None
toxic_type A valid toxic type Yes None
stream The direction of the toxic “upstream” or “downstream” No downstream
toxicity Percentage of toxiciy 1.0 is 100%, 0.5 is 50% etc No 1.0
attributes Dictionary of attributes for the type of toxic No None

create_latency_toxic

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

Argument Description Required Default
for_proxy name for the proxy to attach the toxy Yes None
toxic_name name for this toxy Yes None
latency time in milliseconds to add for latency Yes None
jitter time in milliseconds to jitter No 0

create_bandwith_degradation_toxic

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

Argument Description Required Default
for_proxy name for the proxy to attach the toxy Yes None
toxic_name name for this toxy Yes None
rate desired bandwith rate in KB/s Yes None

create_slow_connection_close_toxic

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

Argument Description Required Default
for_proxy name for the proxy to attach the toxy Yes None
toxic_name name for this toxy Yes None
delay desired close delay in milliseconds Yes None

create_slicer_toxic

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

Argument Description Required Default
for_proxy name for the proxy to attach the toxy Yes None
toxic_name name for this toxy Yes None
average_size size in bytes for the average package Yes None
size_variation variation in bytes of an average pkg (should be smaller than average_size) Yes None
delay time in microseconds to delay each packet by Yes None

create_limiter_toxic

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

Argument Description Required Default
for_proxy name for the proxy to attach the toxy Yes None
toxic_name name for this toxy Yes None
bytes number of bytes to transmit before connection is closed Yes None

delete_toxic

Deletes the a given toxic.

Argument Description Required Default
for_proxy name for the proxy to attach the toxy Yes None
toxic_name name for this toxy Yes None

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
            }
        }    
 ]

Contribute

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.

Develop

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.

Test

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

$ pytest

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

$ tox

Exported Activities

proxy


create_proxy

Type action
Module chaostoxi.proxy.actions
Name create_proxy
Return None

Creates a proxy to which toxics can be added.

Signature:

def create_proxy(proxy_name: str,
                 upstream_host: str,
                 upstream_port: int,
                 listen_host: str = '0.0.0.0',
                 listen_port: int = 0,
                 enabled: bool = True,
                 configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
proxy_name string Yes
upstream_host string Yes
upstream_port integer Yes
listen_host string “0.0.0.0” No
listen_port integer 0 No
enabled boolean true No

Usage:

{
  "name": "create-proxy",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.actions",
    "func": "create_proxy",
    "arguments": {
      "proxy_name": "",
      "upstream_host": "",
      "upstream_port": 0
    }
  }
}
name: create-proxy
provider:
  arguments:
    proxy_name: ''
    upstream_host: ''
    upstream_port: 0
  func: create_proxy
  module: chaostoxi.proxy.actions
  type: python
type: action

delete_proxy

Type action
Module chaostoxi.proxy.actions
Name delete_proxy
Return None

Removes the proxy from the system.

Signature:

def delete_proxy(proxy_name: str,
                 configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
proxy_name string Yes

Usage:

{
  "name": "delete-proxy",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.actions",
    "func": "delete_proxy",
    "arguments": {
      "proxy_name": ""
    }
  }
}
name: delete-proxy
provider:
  arguments:
    proxy_name: ''
  func: delete_proxy
  module: chaostoxi.proxy.actions
  type: python
type: action

disable_proxy

Type action
Module chaostoxi.proxy.actions
Name disable_proxy
Return None

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

Signature:

def disable_proxy(proxy_name: str,
                  configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
proxy_name string Yes

Usage:

{
  "name": "disable-proxy",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.actions",
    "func": "disable_proxy",
    "arguments": {
      "proxy_name": ""
    }
  }
}
name: disable-proxy
provider:
  arguments:
    proxy_name: ''
  func: disable_proxy
  module: chaostoxi.proxy.actions
  type: python
type: action

enable_proxy

Type action
Module chaostoxi.proxy.actions
Name enable_proxy
Return None

Enables a disabled proxy.

Signature:

def enable_proxy(proxy_name: str,
                 configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
proxy_name string Yes

Usage:

{
  "name": "enable-proxy",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.actions",
    "func": "enable_proxy",
    "arguments": {
      "proxy_name": ""
    }
  }
}
name: enable-proxy
provider:
  arguments:
    proxy_name: ''
  func: enable_proxy
  module: chaostoxi.proxy.actions
  type: python
type: action

get_proxy_attribute

Type probe
Module chaostoxi.proxy.probes
Name get_proxy_attribute
Return None

Returns an attribute of a specified proxy.

Signature:

def get_proxy_attribute(proxy_name: str,
                        attribute: str,
                        configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
proxy_name string Yes
attribute string Yes

Usage:

{
  "name": "get-proxy-attribute",
  "type": "probe",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.probes",
    "func": "get_proxy_attribute",
    "arguments": {
      "proxy_name": "",
      "attribute": ""
    }
  }
}
name: get-proxy-attribute
provider:
  arguments:
    attribute: ''
    proxy_name: ''
  func: get_proxy_attribute
  module: chaostoxi.proxy.probes
  type: python
type: probe

modify_proxy

Type action
Module chaostoxi.proxy.actions
Name modify_proxy
Return None

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

Signature:

def modify_proxy(proxy_name: str,
                 listen_address: str = None,
                 upstream_address: str = None,
                 enabled: bool = None,
                 configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
proxy_name string Yes
listen_address string null No
upstream_address string null No
enabled boolean null No

Usage:

{
  "name": "modify-proxy",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.actions",
    "func": "modify_proxy",
    "arguments": {
      "proxy_name": ""
    }
  }
}
name: modify-proxy
provider:
  arguments:
    proxy_name: ''
  func: modify_proxy
  module: chaostoxi.proxy.actions
  type: python
type: action

proxy_exist

Type probe
Module chaostoxi.proxy.probes
Name proxy_exist
Return None

Returns True of False if a given proxy exists.

Signature:

def proxy_exist(proxy_name: str,
                configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
proxy_name string Yes

Usage:

{
  "name": "proxy-exist",
  "type": "probe",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.probes",
    "func": "proxy_exist",
    "arguments": {
      "proxy_name": ""
    }
  }
}
name: proxy-exist
provider:
  arguments:
    proxy_name: ''
  func: proxy_exist
  module: chaostoxi.proxy.probes
  type: python
type: probe

reset

Type action
Module chaostoxi.proxy.actions
Name reset
Return None

Enable all proxies and remove all active toxics

Signature:

def reset(configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required

Usage:

{
  "name": "reset",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.proxy.actions",
    "func": "reset"
  }
}
name: reset
provider:
  func: reset
  module: chaostoxi.proxy.actions
  type: python
type: action

toxic


create_bandwith_degradation_toxic

Type action
Module chaostoxi.toxic.actions
Name create_bandwith_degradation_toxic
Return mapping

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

Signature:

def create_bandwith_degradation_toxic(
        for_proxy: str,
        toxic_name: str,
        rate: int,
        configuration: Dict[str, Dict[str, str]] = None) -> Dict[str, Any]:
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes
rate integer Yes

Usage:

{
  "name": "create-bandwith-degradation-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "create_bandwith_degradation_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": "",
      "rate": 0
    }
  }
}
name: create-bandwith-degradation-toxic
provider:
  arguments:
    for_proxy: ''
    rate: 0
    toxic_name: ''
  func: create_bandwith_degradation_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action

create_latency_toxic

Type action
Module chaostoxi.toxic.actions
Name create_latency_toxic
Return mapping

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

Signature:

def create_latency_toxic(
        for_proxy: str,
        toxic_name: str,
        latency: int,
        jitter: int = 0,
        configuration: Dict[str, Dict[str, str]] = None) -> Dict[str, Any]:
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes
latency integer Yes
jitter integer 0 No

Usage:

{
  "name": "create-latency-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "create_latency_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": "",
      "latency": 0
    }
  }
}
name: create-latency-toxic
provider:
  arguments:
    for_proxy: ''
    latency: 0
    toxic_name: ''
  func: create_latency_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action

create_limiter_toxic

Type action
Module chaostoxi.toxic.actions
Name create_limiter_toxic
Return mapping

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

Signature:

def create_limiter_toxic(
        for_proxy: str,
        toxic_name: str,
        bytes_limit: int,
        configuration: Dict[str, Dict[str, str]] = None) -> Dict[str, Any]:
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes
bytes_limit integer Yes

Usage:

{
  "name": "create-limiter-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "create_limiter_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": "",
      "bytes_limit": 0
    }
  }
}
name: create-limiter-toxic
provider:
  arguments:
    bytes_limit: 0
    for_proxy: ''
    toxic_name: ''
  func: create_limiter_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action

create_slicer_toxic

Type action
Module chaostoxi.toxic.actions
Name create_slicer_toxic
Return mapping

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

Signature:

def create_slicer_toxic(
        for_proxy: str,
        toxic_name: str,
        average_size: int,
        size_variation: int,
        delay: int,
        configuration: Dict[str, Dict[str, str]] = None) -> Dict[str, Any]:
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes
average_size integer Yes
size_variation integer Yes
delay integer Yes

Usage:

{
  "name": "create-slicer-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "create_slicer_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": "",
      "average_size": 0,
      "size_variation": 0,
      "delay": 0
    }
  }
}
name: create-slicer-toxic
provider:
  arguments:
    average_size: 0
    delay: 0
    for_proxy: ''
    size_variation: 0
    toxic_name: ''
  func: create_slicer_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action

create_slow_connection_close_toxic

Type action
Module chaostoxi.toxic.actions
Name create_slow_connection_close_toxic
Return mapping

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

Signature:

def create_slow_connection_close_toxic(
        for_proxy: str,
        toxic_name: str,
        delay: int,
        configuration: Dict[str, Dict[str, str]] = None) -> Dict[str, Any]:
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes
delay integer Yes

Usage:

{
  "name": "create-slow-connection-close-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "create_slow_connection_close_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": "",
      "delay": 0
    }
  }
}
name: create-slow-connection-close-toxic
provider:
  arguments:
    delay: 0
    for_proxy: ''
    toxic_name: ''
  func: create_slow_connection_close_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action

create_timeout_toxic

Type action
Module chaostoxi.toxic.actions
Name create_timeout_toxic
Return mapping

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

Signature:

def create_timeout_toxic(
        for_proxy: str,
        toxic_name: str,
        timeout: int,
        configuration: Dict[str, Dict[str, str]] = None) -> Dict[str, Any]:
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes
timeout integer Yes

Usage:

{
  "name": "create-timeout-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "create_timeout_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": "",
      "timeout": 0
    }
  }
}
name: create-timeout-toxic
provider:
  arguments:
    for_proxy: ''
    timeout: 0
    toxic_name: ''
  func: create_timeout_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action

create_toxic

Type action
Module chaostoxi.toxic.actions
Name create_toxic
Return boolean

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

Signature:

def create_toxic(for_proxy: str,
                 toxic_name: str,
                 toxic_type: str,
                 stream: str = 'downstream',
                 toxicity: float = 1.0,
                 attributes: Dict[str, Any] = None,
                 configuration: Dict[str, Dict[str, str]] = None) -> bool:
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes
toxic_type string Yes
stream string “downstream” No
toxicity number 1.0 No
attributes mapping null No

Usage:

{
  "name": "create-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "create_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": "",
      "toxic_type": ""
    }
  }
}
name: create-toxic
provider:
  arguments:
    for_proxy: ''
    toxic_name: ''
    toxic_type: ''
  func: create_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action

delete_toxic

Type action
Module chaostoxi.toxic.actions
Name delete_toxic
Return None

Deletes the a given toxic.

Signature:

def delete_toxic(for_proxy: str,
                 toxic_name: str,
                 configuration: Dict[str, Dict[str, str]] = None):
    pass

Arguments:

Name Type Default Required
for_proxy string Yes
toxic_name string Yes

Usage:

{
  "name": "delete-toxic",
  "type": "action",
  "provider": {
    "type": "python",
    "module": "chaostoxi.toxic.actions",
    "func": "delete_toxic",
    "arguments": {
      "for_proxy": "",
      "toxic_name": ""
    }
  }
}
name: delete-toxic
provider:
  arguments:
    for_proxy: ''
    toxic_name: ''
  func: delete_toxic
  module: chaostoxi.toxic.actions
  type: python
type: action