Official support use of the Ansible API directly

[ericwb]

Proposal: Official support use of the Ansible API directly

Author: Eric Brown <@ericwb> IRC: browne

Date: 2018/01/26

• Status: New
• Proposal type: core
• Targeted Release: 2.6
• Associated PR: none
• Estimated time to implement: 3 months

Motivation

The following link describes how to use Ansible directly even though Ansible is not intended for direct consumption. http://docs.ansible.com/ansible/latest/dev_guide/developing_api.html

But I think there is interest in having such direct consumption. Other projects would like to call into the Ansible API directly to avoid having to do exec() calls to the CLI.

Problems

I feel this will satisfy consumers of Ansible that wish to call into the API direct via Python code instead of having to shell out to the CLI. Although it is possible to call the code today (using above doc link), it changes so frequently between major and minor releases.

Solution proposal

I propose that a standard API layer that is maintained as part of the Ansible code base that does not change with version to version without deprecation, etc. That way, exploiters of Ansible who wish to call the code directly can call a consistent functions to "run a playbook", etc.

Dependencies (optional)

N/A

Testing (optional)

The new API should be fully unit tested to ensure no breakages with core code changes.

Documentation (optional)

Definitely should be documented as the proper interface to call Ansible code.

Anything else?

[tima]

@ericwb: Just was browsing through proposals and saw this one. What I think you are describing is exactly what the ansible-runner project was created. It's what AWX/Tower uses to execute and manage engine/core core jobs. https://github.com/ansible/ansible-runner

[ericwb]

@tima Thanks but the link you provided is just a code wrapper around calls to the CLI. Instead, this request is to have a stable API interface that can be called directly and not through CLI exec calls.

[agaffney]

The internal API has been in flux since at least the days of 2.0, and it's probably not going to slow down any time soon. At this point, it's probably not practical (for the Ansible devs) to maintain the internal API for external consumption. The only supported stable interface is the CLI utilities.

[sivel]

Thanks but the link you provided is just a code wrapper around calls to the CLI. Instead, this request is to have a stable API interface that can be called directly and not through CLI exec calls.

We have no plans to offer official support for the python API within ansible to execute ansible.

For the foreseeable future, ansible-runner is the supported and official way to programmatically execute ansible.