Package: chaostoolkit-ansible
Chaos toolkit Extension for using ansible as driverThis project is a collection ofactionsandprobes, gathered as an extension to theChaos Toolkit.Please NOTEThis extension is in theearlystages of development. Please feel free to create an issue in case of needed ehancement or misfunctioning.InstallThis package requires Python 3.6+To be used from your experiment, this package must be installed in the Python environment wherechaostoolkitalready lives.$ pip install -U chaostoolkit-ansiblePrinciplesThis chaos toolkit driver provides you an easy way to execute probe and/or actions using ansible modules. By using it, you can execute tasks, gather facts, ... on remote systemsUsageBasicProbesTo use the probes from this package, add the following to your experiment file:In JSON:"steady-state-hypothesis":{"title":"Tests","probes":[{"type":"probe","name":"test-current-directory","tolerance":{"type":"jsonpath","path":"$.*.task","expect":"/home/me"},"provider":{"type":"python","module":"chaosansible.probes","func":"chaosansible_probe","arguments":{"host_list":["myserver1","myserver2"],"facts":"yes","ansible":{"module":"shell","args":"pwd"}}}}]}In YAML:---steady-state-hypothesis:title:The current working directory must be /home/meprobes:-type:probename:test-current-directorytolerance:type:jsonpathtarget:"$.*.task"pattern:/home/meprovider:type:pythonmodule:chaosansible.probesfunc:chaosansible_probearguments:host_list:["myserver1","myserver2"]facts:Trueansible:module:shellargs:pwdThat's it!Probes can be gathered by using the stdout of an ansible task or through the ansible gather_facts module. Each time chaostoolkit-ansible runs, it returns a json that can be used in tolerance (using jsonpath, regex, ...)This json is always formatted the same way (Exemple for a two targets host_list):{"target1":{"fact":" -> JSON result of the ansible gather_facts","task":" -> String result containing the stdout value of the task result - Empty when ansible task do not return stdout"},"target2":{"fact":"...","task":"..."}}ActionsTo use the actions from this package, add the following to your experiment file:In JSON:"method":[{"type":"action","name":"delete-etc-hosts-file","provider":{"type":"python","module":"chaosansible.actions","func":"chaosansible_run","arguments":{"host_list":["server1","server2"],"become":true,"ansible":{"module":"file","args":{"path":"/etc/hosts","state":"absent"}}}}}]In YAML:---method:-type:actionname:delete-etc-hosts-fileprovider:type:pythonmodule:chaosansible.actionsfunc:chaosansible_runarguments:host_list:["server1","server2"]become:Trueansible:module:fileargs:path:/etc/hostsstate:absentDetailled usageConfiguration blockThe configuration block can be used to specify specific parameters to use. This block can be omit unless you really need to change default ansible parameters to run your exeperimentConfiguration variables that can be used by this driver are:ansible_module_path: Path of your ansible libraryansible_become_user: Privileged user used when you call privilege escalation (root by default)ansible_ssh_private_key: Your ssh private key used to connect to targets (~/.ssh/id_rsa by default)ansible_user: User on target host used by ansible (current username by default)become_ask_pass: Password to escalate privileged when sudo needs oneansible_extra_ssh_args: SSH extra argsIn case you need to change one/or many default configuration(s), you can specify your value using the configuration blockPlease feel free to ask, if you need access to other ansible configuration parametersIn JSON:"configuration":{"ansible_ssh_private_key":"/home/me/.ssh/mykey"}In YAML:configuration:ansible_ssh_private_key:"/home/me/.ssh/mykey"Argumentschaosansible_run and chaosansible_probes use arguements (Most argument are classical ansible parameters):ArgumentTypeRequiredDefault valueDescriptionhost_listArraylocalhostList of host to usefactsboolfalseGather_factsbecomeboolfalseEscalate privilege to run taskrun_onceboolfalseRun the task only once on one targetnum_targetstrall"all" or "x" where x is an integer. Run the task to only x target among the host_list. Ideal to create random eventansibledict{}Execute ansible task. Cf ansible dict format. If ansible is not set, no task except ansible gather_facts (if facts set to True)Ansible dict format:Classic ansible task are in the form:name:task nameansible-module-name:module-parameter1:value1module-parameter2:value2This is translate into chaos experiment file like this:
In JSON"ansible":{"module":"ansible-module-name","args":{"module-parameter1":"value1","module-parameter2":"value2"}}In YAMLansible:module:ansible-module-nameargs:module-parameter1:value1module-parameter2:value2Example with the ansible mount module (Umount a filesystem):In JSON"ansible":{"module":"mount","args":{"path":"/data","state":"unmounted"}}In YAMLansible:module:mountargs:path:/datastate:unmountedExample of usageDelete /etc/hosts file on 2 random servers out of 5In JSON"method":[{"type":"action","name":"delete-etc-hosts-file","provider":{"type":"python","module":"chaosansible.actions","func":"chaosansible_run","arguments":{"host_list":["server1","server2","server3","server4","server5"],"num_target":"2","become":true,"ansible":{"module":"file","args":{"path":"/etc/hosts","state":"absent"}}}}}]In YAMLmethod:-type:actionname:delete-etc-hosts-fileprovider:type:pythonmodule:chaosansible.actionsfunc:chaosansible_runarguments:host_list:["server1","server2","server3","server4","server5"]become:Truenum_target:"2"ansible:module:fileargs:path:/etc/hostsstate:absentRun 100% cpu load on 3 server out of 5In JSON"method":[{"type":"action","name":"delete-etc-hosts-file","provider":{"type":"python","module":"chaosansible.actions","func":"chaosansible_run","arguments":{"host_list":["server1","server2","server3","server4","server5"],"num_target":"3","ansible":{"module":"shell","args":{"cmd":"stress-ng --cpu 0 --cpu-method matrixprod -t 60s",}}}}}]In YAMLmethod:-type:actionname:delete-etc-hosts-fileprovider:type:pythonmodule:chaosansible.actionsfunc:chaosansible_runarguments:host_list:["server1","server2","server3","server4","server5"]become:Truenum_target:"3"ansible:module:shellargs:cmd:stress-ng --cpu 0 --cpu-method matrixprod -t 60sContributeIf 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
usualPEP 8code style, sprinkling with tests and submit a PR for
review.The Chaos Toolkit projects require all contributors must sign aDeveloper Certificate of Originon 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.DevelopIf you wish to develop on this project, make sure to install the development
dependencies. But first,create a virtual environmentand then install
those dependencies.$pipinstall-rrequirements-dev.txt-rrequirements.txtThen, point your environment to this directory:$pipinstall-e.Now, you can edit the files and they will be automatically be seen by your
environment, even when running from thechaoscommand locally.TestTo run the tests for the project execute the following:$ pytest