diff --git a/README.md b/README.md index 167fd01..f953250 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,81 @@ # cotea -cotea: Ansible control tool + +### cotea is: +Tool that provides Python API to run Ansible programmatically. + +### cotea allows: +- **To control** Ansible execution by iterating over the Ansible plays and tasks +- **To embed** Ansible into other systems +- **To debug** Ansible execution by getting the values of Ansible variables and by retrieving the results of the execution of Ansible tasks/plays + +## Installation +At the moment, only installation from source is possible. In the future, it is planned to install cotea using pip. +It is assumed that Ansible is installed in the current environment. + +You need just to clone this project: +```bash +git clone https://github.com/ispras/cotea +``` +and use **from cotea.src.** to import any of cotea objects being in the same directory as the cotea folder. + +## Quick start +```python +from cotea.src.runner import runner +from cotea.src.arguments_maker import argument_maker + + +inv_path = "/path/to/inventory" +playbook_path = "/path/to/playbook" + +am = argument_maker() +am.add_arg("-i", inv_path) + +r = runner(playbook_path, am) + +while r.has_next_play(): + setup_ok = r.setup_play_for_run() + current_play = r.get_cur_play_name() + print("PLAY:", current_play) + + if setup_ok: + while r.has_next_task(): + next_task = r.get_next_task_name() + print("\tTASK:", next_task) + + r.run_next_task() + +r.finish_ansible() +``` +Any argument of the "ansible-playbook" command can be passed by using **argument_maker** objects. +The launch and control of the Ansible is carried out using the **runner** object. + +## Debugging + +```python +# imports and object creation... + +specific_play = "s_play" +specific_task = "s_task" +s_var_name = "s_var" + +while r.has_next_play(): + setup_ok = r.setup_play_for_run() + current_play = r.get_cur_play_name() + + if setup_ok: + while r.has_next_task(): + next_task = r.get_next_task_name() + if current_play == specific_play and next_task == specific_task: + # getting variable at specific execution point + s_var_value = r.get_variable(s_var_name) + + r.run_next_task() + +r.finish_ansible() + +if r.was_error(): + print("Ansible error was:", r.get_error_msg()) +``` +With the help of cotea one can do certain things dynamically at specific Ansible execution points. Getting the value of a specific variable at a specific execution point is shown above (the point is determined by a pair of Ansible play and task). If ansible exits with an error one can get the error message programmatically without processing a huge log file. + +A detailed overview of all interfaces is provided in [cotea documentation](https://github.com/ispras/cotea/blob/main/docs/cotea_docs.md). \ No newline at end of file diff --git a/docs/cotea_docs.md b/docs/cotea_docs.md new file mode 100644 index 0000000..1549c19 --- /dev/null +++ b/docs/cotea_docs.md @@ -0,0 +1 @@ +# cotea documentation \ No newline at end of file diff --git a/src/__pycache__/ansible_execution_sync.cpython-38.pyc b/src/__pycache__/ansible_execution_sync.cpython-38.pyc new file mode 100644 index 0000000..53f35e4 Binary files /dev/null and b/src/__pycache__/ansible_execution_sync.cpython-38.pyc differ diff --git a/src/__pycache__/arguments_maker.cpython-38.pyc b/src/__pycache__/arguments_maker.cpython-38.pyc new file mode 100644 index 0000000..4122fb7 Binary files /dev/null and b/src/__pycache__/arguments_maker.cpython-38.pyc differ diff --git a/src/__pycache__/runner.cpython-38.pyc b/src/__pycache__/runner.cpython-38.pyc new file mode 100644 index 0000000..01c43ba Binary files /dev/null and b/src/__pycache__/runner.cpython-38.pyc differ diff --git a/ansible_execution_sync.py b/src/ansible_execution_sync.py similarity index 100% rename from ansible_execution_sync.py rename to src/ansible_execution_sync.py diff --git a/arguments_maker.py b/src/arguments_maker.py similarity index 100% rename from arguments_maker.py rename to src/arguments_maker.py diff --git a/runner.py b/src/runner.py similarity index 95% rename from runner.py rename to src/runner.py index 1ad8c9d..775414f 100644 --- a/runner.py +++ b/src/runner.py @@ -14,16 +14,16 @@ from ansible.plugins.strategy.linear import StrategyModule from ansible.executor.task_queue_manager import TaskQueueManager -from cotea.ansible_execution_sync import ans_sync -from cotea.arguments_maker import argument_maker -from cotea.wrappers.get_batches_wrapper import get_batches_wrapper -from cotea.wrappers.strategy_run_wrapper import strategy_run_wrapper -from cotea.wrappers.get_next_task_wrapper import get_next_task_wrapper -from cotea.wrappers.wait_pending_wrapper import wait_pending_wrapper -from cotea.wrappers.tqm_run_wrapper import tqm_run_wrapper -from cotea.wrappers.get_batch_len_wrapper import get_batch_len_wrapper -from cotea.wrappers.pbcli_run_wrapper import pbcli_run_wrapper -from cotea.wrappers.play_prereqs_wrapper import play_prereqs_wrapper +from cotea.src.ansible_execution_sync import ans_sync +from cotea.src.arguments_maker import argument_maker +from cotea.src.wrappers.get_batches_wrapper import get_batches_wrapper +from cotea.src.wrappers.strategy_run_wrapper import strategy_run_wrapper +from cotea.src.wrappers.get_next_task_wrapper import get_next_task_wrapper +from cotea.src.wrappers.wait_pending_wrapper import wait_pending_wrapper +from cotea.src.wrappers.tqm_run_wrapper import tqm_run_wrapper +from cotea.src.wrappers.get_batch_len_wrapper import get_batch_len_wrapper +from cotea.src.wrappers.pbcli_run_wrapper import pbcli_run_wrapper +from cotea.src.wrappers.play_prereqs_wrapper import play_prereqs_wrapper class runner: diff --git a/src/wrappers/__pycache__/get_batch_len_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/get_batch_len_wrapper.cpython-38.pyc new file mode 100644 index 0000000..6454538 Binary files /dev/null and b/src/wrappers/__pycache__/get_batch_len_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/get_batches_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/get_batches_wrapper.cpython-38.pyc new file mode 100644 index 0000000..46c93fe Binary files /dev/null and b/src/wrappers/__pycache__/get_batches_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/get_next_task_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/get_next_task_wrapper.cpython-38.pyc new file mode 100644 index 0000000..eef1769 Binary files /dev/null and b/src/wrappers/__pycache__/get_next_task_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/pbcli_run_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/pbcli_run_wrapper.cpython-38.pyc new file mode 100644 index 0000000..ef2eac1 Binary files /dev/null and b/src/wrappers/__pycache__/pbcli_run_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/play_prereqs_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/play_prereqs_wrapper.cpython-38.pyc new file mode 100644 index 0000000..c6c6d6e Binary files /dev/null and b/src/wrappers/__pycache__/play_prereqs_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/strategy_run_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/strategy_run_wrapper.cpython-38.pyc new file mode 100644 index 0000000..25f65c5 Binary files /dev/null and b/src/wrappers/__pycache__/strategy_run_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/tqm_run_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/tqm_run_wrapper.cpython-38.pyc new file mode 100644 index 0000000..bbc34df Binary files /dev/null and b/src/wrappers/__pycache__/tqm_run_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/wait_pending_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/wait_pending_wrapper.cpython-38.pyc new file mode 100644 index 0000000..33a937f Binary files /dev/null and b/src/wrappers/__pycache__/wait_pending_wrapper.cpython-38.pyc differ diff --git a/src/wrappers/__pycache__/wrapper_base.cpython-38.pyc b/src/wrappers/__pycache__/wrapper_base.cpython-38.pyc new file mode 100644 index 0000000..0a396fd Binary files /dev/null and b/src/wrappers/__pycache__/wrapper_base.cpython-38.pyc differ diff --git a/wrappers/get_batch_len_wrapper.py b/src/wrappers/get_batch_len_wrapper.py similarity index 89% rename from wrappers/get_batch_len_wrapper.py rename to src/wrappers/get_batch_len_wrapper.py index b6e9a08..d9762f7 100644 --- a/wrappers/get_batch_len_wrapper.py +++ b/src/wrappers/get_batch_len_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps ansible.inventory.manager.InventoryManager.restrict_to_hosts() diff --git a/wrappers/get_batches_wrapper.py b/src/wrappers/get_batches_wrapper.py similarity index 94% rename from wrappers/get_batches_wrapper.py rename to src/wrappers/get_batches_wrapper.py index ac96635..4e9c6ad 100644 --- a/wrappers/get_batches_wrapper.py +++ b/src/wrappers/get_batches_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps ansible.executor.playbook_executor.PlaybookExecutor._get_serialized_batches() diff --git a/wrappers/get_next_task_wrapper.py b/src/wrappers/get_next_task_wrapper.py similarity index 97% rename from wrappers/get_next_task_wrapper.py rename to src/wrappers/get_next_task_wrapper.py index 20a0644..c508f3d 100644 --- a/wrappers/get_next_task_wrapper.py +++ b/src/wrappers/get_next_task_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps ansible.plugins.strategy.linear.StrategyModule._get_next_task_lockstep() diff --git a/wrappers/pbcli_run_wrapper.py b/src/wrappers/pbcli_run_wrapper.py similarity index 89% rename from wrappers/pbcli_run_wrapper.py rename to src/wrappers/pbcli_run_wrapper.py index c5e5ea9..5eebe70 100644 --- a/wrappers/pbcli_run_wrapper.py +++ b/src/wrappers/pbcli_run_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps from ansible.cli.playbook.PlaybookCLI.run() diff --git a/wrappers/play_prereqs_wrapper.py b/src/wrappers/play_prereqs_wrapper.py similarity index 92% rename from wrappers/play_prereqs_wrapper.py rename to src/wrappers/play_prereqs_wrapper.py index be00d53..787d308 100644 --- a/wrappers/play_prereqs_wrapper.py +++ b/src/wrappers/play_prereqs_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps from ansible.cli.CLI._play_prereqs() diff --git a/wrappers/strategy_run_wrapper.py b/src/wrappers/strategy_run_wrapper.py similarity index 96% rename from wrappers/strategy_run_wrapper.py rename to src/wrappers/strategy_run_wrapper.py index a2535e8..eb4a99c 100644 --- a/wrappers/strategy_run_wrapper.py +++ b/src/wrappers/strategy_run_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps ansible.plugins.strategy.linear.StrategyModule.run() diff --git a/wrappers/tqm_run_wrapper.py b/src/wrappers/tqm_run_wrapper.py similarity index 96% rename from wrappers/tqm_run_wrapper.py rename to src/wrappers/tqm_run_wrapper.py index a420fc7..5c92d0b 100644 --- a/wrappers/tqm_run_wrapper.py +++ b/src/wrappers/tqm_run_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps ansible.executor.task_queue_manager.TaskQueueManager.run() diff --git a/wrappers/wait_pending_wrapper.py b/src/wrappers/wait_pending_wrapper.py similarity index 98% rename from wrappers/wait_pending_wrapper.py rename to src/wrappers/wait_pending_wrapper.py index cad93a0..169ced0 100644 --- a/wrappers/wait_pending_wrapper.py +++ b/src/wrappers/wait_pending_wrapper.py @@ -1,4 +1,4 @@ -from cotea.wrappers.wrapper_base import wrapper_base +from cotea.src.wrappers.wrapper_base import wrapper_base # wraps ansible.plugins.strategy.StrategyBase._wait_on_pending_results() diff --git a/wrappers/wrapper_base.py b/src/wrappers/wrapper_base.py similarity index 100% rename from wrappers/wrapper_base.py rename to src/wrappers/wrapper_base.py