f1a060743a
* Doc build warning/broken link clean-a-palooza, WIP commit 1.
* Fixed broken anchor
* Fixing additional broken links; converting from doc to ref.
* Fix anchor
(cherry picked from commit 381359a8f8)
204 lines
7.1 KiB
ReStructuredText
204 lines
7.1 KiB
ReStructuredText
.. _developing_api:
|
|
|
|
Python API
|
|
==========
|
|
|
|
.. note:: This document is out of date: 'ansible.parsing.dataloader' and 'ansible.runner' are not available in the current version of Ansible.
|
|
|
|
.. contents:: Topics
|
|
|
|
Please note that while we make this API available it is not intended for direct consumption, it is here
|
|
for the support of the Ansible command line tools. We try not to make breaking changes but we reserve the
|
|
right to do so at any time if it makes sense for the Ansible toolset.
|
|
|
|
|
|
The following documentation is provided for those that still want to use the API directly, but be mindful this is not something the Ansible team supports.
|
|
|
|
There are several interesting ways to use Ansible from an API perspective. You can use
|
|
the Ansible python API to control nodes, you can extend Ansible to respond to various python events, you can
|
|
write various plugins, and you can plug in inventory data from external data sources. This document
|
|
covers the execution and Playbook API at a basic level.
|
|
|
|
If you are looking to use Ansible programmatically from something other than Python, trigger events asynchronously,
|
|
or have access control and logging demands, take a look at :doc:`../tower`
|
|
as it has a very nice REST API that provides all of these things at a higher level.
|
|
|
|
Ansible is written in its own API so you have a considerable amount of power across the board.
|
|
This chapter discusses the Python API.
|
|
|
|
.. _python_api:
|
|
|
|
The Python API is very powerful, and is how the all the ansible CLI tools are implemented.
|
|
In version 2.0 the core ansible got rewritten and the API was mostly rewritten.
|
|
|
|
.. note:: Ansible relies on forking processes, as such the API is not thread safe.
|
|
|
|
.. _python_api_20:
|
|
|
|
Python API 2.0
|
|
--------------
|
|
|
|
In 2.0 things get a bit more complicated to start, but you end up with much more discrete and readable classes::
|
|
|
|
|
|
#!/usr/bin/env python
|
|
|
|
import json
|
|
import shutil
|
|
from collections import namedtuple
|
|
from ansible.parsing.dataloader import DataLoader
|
|
from ansible.vars.manager import VariableManager
|
|
from ansible.inventory.manager import InventoryManager
|
|
from ansible.playbook.play import Play
|
|
from ansible.executor.task_queue_manager import TaskQueueManager
|
|
from ansible.plugins.callback import CallbackBase
|
|
import ansible.constants as C
|
|
|
|
class ResultCallback(CallbackBase):
|
|
"""A sample callback plugin used for performing an action as results come in
|
|
|
|
If you want to collect all results into a single object for processing at
|
|
the end of the execution, look into utilizing the ``json`` callback plugin
|
|
or writing your own custom callback plugin
|
|
"""
|
|
def v2_runner_on_ok(self, result, **kwargs):
|
|
"""Print a json representation of the result
|
|
|
|
This method could store the result in an instance attribute for retrieval later
|
|
"""
|
|
host = result._host
|
|
print(json.dumps({host.name: result._result}, indent=4))
|
|
|
|
Options = namedtuple('Options', ['connection', 'module_path', 'forks', 'become', 'become_method', 'become_user', 'check', 'diff'])
|
|
# initialize needed objects
|
|
loader = DataLoader()
|
|
options = Options(connection='local', module_path=['/path/to/mymodules'], forks=100, become=None, become_method=None, become_user=None, check=False,
|
|
diff=False)
|
|
passwords = dict(vault_pass='secret')
|
|
|
|
# Instantiate our ResultCallback for handling results as they come in
|
|
results_callback = ResultCallback()
|
|
|
|
# create inventory and pass to var manager
|
|
# use path to host config file as source or hosts in a comma separated string
|
|
inventory = InventoryManager(loader=loader, sources='localhost,')
|
|
variable_manager = VariableManager(loader=loader, inventory=inventory)
|
|
|
|
# create play with tasks
|
|
play_source = dict(
|
|
name = "Ansible Play",
|
|
hosts = 'localhost',
|
|
gather_facts = 'no',
|
|
tasks = [
|
|
dict(action=dict(module='shell', args='ls'), register='shell_out'),
|
|
dict(action=dict(module='debug', args=dict(msg='{{shell_out.stdout}}')))
|
|
]
|
|
)
|
|
play = Play().load(play_source, variable_manager=variable_manager, loader=loader)
|
|
|
|
# actually run it
|
|
tqm = None
|
|
try:
|
|
tqm = TaskQueueManager(
|
|
inventory=inventory,
|
|
variable_manager=variable_manager,
|
|
loader=loader,
|
|
options=options,
|
|
passwords=passwords,
|
|
stdout_callback=results_callback, # Use our custom callback instead of the ``default`` callback plugin
|
|
)
|
|
result = tqm.run(play)
|
|
finally:
|
|
if tqm is not None:
|
|
tqm.cleanup()
|
|
|
|
# Remove ansible tmpdir
|
|
shutil.rmtree(C.DEFAULT_LOCAL_TMP, True)
|
|
|
|
|
|
.. _python_api_old:
|
|
|
|
Python API pre 2.0
|
|
------------------
|
|
|
|
It's pretty simple::
|
|
|
|
import ansible.runner
|
|
|
|
runner = ansible.runner.Runner(
|
|
module_name='ping',
|
|
module_args='',
|
|
pattern='web*',
|
|
forks=10
|
|
)
|
|
datastructure = runner.run()
|
|
|
|
The run method returns results per host, grouped by whether they
|
|
could be contacted or not. Return types are module specific, as
|
|
expressed in the :doc:`../modules` documentation.::
|
|
|
|
{
|
|
"dark" : {
|
|
"web1.example.com" : "failure message"
|
|
},
|
|
"contacted" : {
|
|
"web2.example.com" : 1
|
|
}
|
|
}
|
|
|
|
A module can return any type of JSON data it wants, so Ansible can
|
|
be used as a framework to rapidly build powerful applications and scripts.
|
|
|
|
.. _detailed_api_old_example:
|
|
|
|
Detailed API Example
|
|
````````````````````
|
|
|
|
The following script prints out the uptime information for all hosts::
|
|
|
|
#!/usr/bin/python
|
|
|
|
import ansible.runner
|
|
import sys
|
|
|
|
# construct the ansible runner and execute on all hosts
|
|
results = ansible.runner.Runner(
|
|
pattern='*', forks=10,
|
|
module_name='command', module_args='/usr/bin/uptime',
|
|
).run()
|
|
|
|
if results is None:
|
|
print "No hosts found"
|
|
sys.exit(1)
|
|
|
|
print "UP ***********"
|
|
for (hostname, result) in results['contacted'].items():
|
|
if not 'failed' in result:
|
|
print "%s >>> %s" % (hostname, result['stdout'])
|
|
|
|
print "FAILED *******"
|
|
for (hostname, result) in results['contacted'].items():
|
|
if 'failed' in result:
|
|
print "%s >>> %s" % (hostname, result['msg'])
|
|
|
|
print "DOWN *********"
|
|
for (hostname, result) in results['dark'].items():
|
|
print "%s >>> %s" % (hostname, result)
|
|
|
|
Advanced programmers may also wish to read the source to ansible itself,
|
|
for it uses the API (with all available options) to implement the ``ansible``
|
|
command line tools (``lib/ansible/cli/``).
|
|
|
|
.. seealso::
|
|
|
|
:doc:`developing_inventory`
|
|
Developing dynamic inventory integrations
|
|
:doc:`developing_modules`
|
|
How to develop modules
|
|
:doc:`developing_plugins`
|
|
How to develop plugins
|
|
`Development Mailing List <http://groups.google.com/group/ansible-devel>`_
|
|
Mailing list for development topics
|
|
`irc.freenode.net <http://irc.freenode.net>`_
|
|
#ansible IRC chat channel
|
|
|