From 26e41c2a74a5e750c01b5620ab4078d7f3da573a Mon Sep 17 00:00:00 2001 From: David Shrewsbury Date: Thu, 28 Oct 2021 14:11:38 -0400 Subject: [PATCH] Add test and docs for running roles via API --- ansible_runner/interface.py | 3 +++ docs/python_interface.rst | 13 ++++++++++--- .../debug/project/roles/hello_world/tasks/main.yml | 3 +++ test/integration/test_interface.py | 13 +++++++++++++ 4 files changed, 29 insertions(+), 3 deletions(-) create mode 100644 test/integration/fixtures/projects/debug/project/roles/hello_world/tasks/main.yml diff --git a/ansible_runner/interface.py b/ansible_runner/interface.py index f31fec2e8..4c8714a47 100644 --- a/ansible_runner/interface.py +++ b/ansible_runner/interface.py @@ -153,6 +153,7 @@ def run(**kwargs): - A text INI formatted string - A list of inventory sources, or an empty list to disable passing inventory + :param role: Name of the role to execute. :param roles_path: Directory or list of directories to assign to ANSIBLE_ROLES_PATH :param envvars: Environment variables to be used when running Ansible. Environment variables will also be read from ``env/envvars`` in ``private_data_dir`` @@ -212,6 +213,8 @@ def run(**kwargs): :type json_mode: bool :type playbook: str or filename or list :type inventory: str or dict or list + :type role: str + :type roles_path: dict or list :type envvars: dict :type extravars: dict :type passwords: dict diff --git a/docs/python_interface.rst b/docs/python_interface.rst index 8905caddf..1fed65b91 100644 --- a/docs/python_interface.rst +++ b/docs/python_interface.rst @@ -200,6 +200,13 @@ Usage examples print("Final status:") print(r.stats) +.. code-block:: python + + # run the role named 'myrole' contained in the '/project/roles' directory + r = ansible_runner.run(private_data_dir='/tmp/demo', role='myrole') + print("{}: {}".format(r.status, r.rc)) + print(r.stats) + .. code-block:: python # run ansible/generic commands in interactive mode within container @@ -219,7 +226,7 @@ Usage examples .. code-block:: python - # run ansible/generic commands in interactive mode locally + # run ansible/generic commands in interactive mode locally out, err, rc = ansible_runner.run_command( executable_cmd='ansible-playbook', cmdline_args=['gather.yaml', '-i', 'inventory', '-vvvv', '-k'], @@ -233,7 +240,7 @@ Usage examples .. code-block:: python - # get plugin docs from within container + # get plugin docs from within container out, err = ansible_runner.get_plugin_docs( plugin_names=['vyos.vyos.vyos_command'], plugin_type='module', @@ -246,7 +253,7 @@ Usage examples .. code-block:: python - # get plugin docs from within container in async mode + # get plugin docs from within container in async mode thread_obj, runner_obj = ansible_runner.get_plugin_docs_async( plugin_names=['ansible.netcommon.cli_config', 'ansible.netcommon.cli_command'], plugin_type='module', diff --git a/test/integration/fixtures/projects/debug/project/roles/hello_world/tasks/main.yml b/test/integration/fixtures/projects/debug/project/roles/hello_world/tasks/main.yml new file mode 100644 index 000000000..c6de4a87b --- /dev/null +++ b/test/integration/fixtures/projects/debug/project/roles/hello_world/tasks/main.yml @@ -0,0 +1,3 @@ +- name: "Hello World role" + debug: + msg: "Hello World!" diff --git a/test/integration/test_interface.py b/test/integration/test_interface.py index bd43d5b6a..d1d5298c9 100644 --- a/test/integration/test_interface.py +++ b/test/integration/test_interface.py @@ -342,3 +342,16 @@ def test_get_inventory_within_container(project_fixtures, runtime): ) assert 'host_1' in out['ungrouped']['hosts'] assert 'host_2' in out['ungrouped']['hosts'] + + +def test_run_role(project_fixtures): + ''' Test that we can run a role via the API. ''' + private_data_dir = project_fixtures / 'debug' + + res = run( + private_data_dir=private_data_dir, + role='hello_world', + ) + stdout = res.stdout.read() + assert res.rc == 0, stdout + assert 'Hello World!' in stdout