Merge pull request #896 from Shrews/backport/891/release_2.1

[release_2.1] Add test and docs for running roles via API

Backport of PR #891
(cherry picked from commit 7185416)

Reviewed-by: Sam Doran <[email protected]>
Reviewed-by: None <None>

Author: ansible-zuul[bot]

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

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 '<private_data_dir>/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',

test/integration/fixtures/projects/debug/project/roles/hello_world/tasks/main.yml

@@ -0,0 +1,3 @@
+- name: "Hello World role"
+  debug:
+      msg: "Hello World!"

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