ansible/docs/docsite/rst/dev_guide/developing_api.rst

130 lines
5.7 KiB
ReStructuredText
Raw Normal View History

.. _developing_api:
**********
2016-09-23 22:48:37 +02:00
Python API
**********
2016-09-23 22:48:37 +02:00
.. contents:: Topics
.. note:: This API is intended for internal Ansible use. Ansible may make changes to this API at any time that could break backward compatibility with older versions of the API. Because of this, external use is not supported by Ansible.
2016-09-23 22:48:37 +02:00
2018-03-02 23:51:48 +01:00
There are several 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 plugins, and you can plug in inventory data from external data sources. This document
gives a basic overview and examples of the Ansible execution and playbook API.
2016-09-23 22:48:37 +02:00
If you would like to use Ansible programmatically from a language other than Python, trigger events asynchronously,
or have access control and logging demands, please see the `Ansible Tower documentation <https://docs.ansible.com/ansible-tower/>`_.
2016-09-23 22:48:37 +02:00
2018-03-02 23:51:48 +01:00
.. note:: Because Ansible relies on forking processes, this API is not thread safe.
2016-09-23 22:48:37 +02:00
.. _python_api_example:
2016-09-23 22:48:37 +02:00
Python API example
==================
2016-09-23 22:48:37 +02:00
2018-03-02 23:51:48 +01:00
This example is a simple demonstration that shows how to minimally run a couple of tasks::
2016-09-23 22:48:37 +02:00
#!/usr/bin/env python
import json
import shutil
from ansible.module_utils.common.collections import ImmutableDict
2016-09-23 22:48:37 +02:00
from ansible.parsing.dataloader import DataLoader
2017-09-20 17:33:38 +02:00
from ansible.vars.manager import VariableManager
from ansible.inventory.manager import InventoryManager
2016-09-23 22:48:37 +02:00
from ansible.playbook.play import Play
from ansible.executor.task_queue_manager import TaskQueueManager
from ansible.plugins.callback import CallbackBase
from ansible import context
import ansible.constants as C
2016-09-23 22:48:37 +02:00
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
2017-09-20 17:33:38 +02:00
print(json.dumps({host.name: result._result}, indent=4))
2016-09-23 22:48:37 +02:00
# since the API is constructed for CLI it expects certain options to always be set in the context object
context.CLIARGS = ImmutableDict(connection='local', module_path=['/to/mymodules'], forks=10, become=None,
become_method=None, become_user=None, check=False, diff=False)
2016-09-23 22:48:37 +02:00
# initialize needed objects
loader = DataLoader() # Takes care of finding and reading yaml, json and ini files
2016-09-23 22:48:37 +02:00
passwords = dict(vault_pass='secret')
2018-03-02 23:51:48 +01:00
# Instantiate our ResultCallback for handling results as they come in. Ansible expects this to be one of its main display outlets
2016-09-23 22:48:37 +02:00
results_callback = ResultCallback()
# create inventory, use path to host config file as source or hosts in a comma separated string
inventory = InventoryManager(loader=loader, sources='localhost,')
2018-10-28 21:55:41 +01:00
# variable manager takes care of merging all the different sources to give you a unified view of variables available in each context
2017-09-20 17:33:38 +02:00
variable_manager = VariableManager(loader=loader, inventory=inventory)
2016-09-23 22:48:37 +02:00
# Instantiate task queue manager, which takes care of forking
# and setting up all objects to iterate over host list and tasks.
# IMPORTANT: This also adds library dirs paths to the module loader
# IMPORTANT: and so it must be initialized before calling `Play.load()`.
tqm = TaskQueueManager(
inventory=inventory,
variable_manager=variable_manager,
loader=loader,
passwords=passwords,
stdout_callback=results_callback, # Use our custom callback instead of the ``default`` callback plugin, which prints to stdout
)
2018-10-28 21:55:41 +01:00
# create data structure that represents our play, including tasks, this is basically what our YAML loader does internally.
2016-09-23 22:48:37 +02:00
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}}')))
]
)
# Create play object, playbook objects use .load instead of init or new methods,
# this will also automatically create the task objects from the info provided in play_source
2016-09-23 22:48:37 +02:00
play = Play().load(play_source, variable_manager=variable_manager, loader=loader)
# Actually run it
2016-09-23 22:48:37 +02:00
try:
result = tqm.run(play) # most interesting data for a play is actually sent to the callback's methods
2016-09-23 22:48:37 +02:00
finally:
2018-10-28 21:55:41 +01:00
# we always need to cleanup child procs and the structures we use to communicate with them
2016-09-23 22:48:37 +02:00
if tqm is not None:
tqm.cleanup()
2018-05-09 10:08:59 +02:00
# Remove ansible tmpdir
shutil.rmtree(C.DEFAULT_LOCAL_TMP, True)
2016-09-23 22:48:37 +02:00
.. note:: Ansible emits warnings and errors via the display object, which prints directly to stdout, stderr and the Ansible log.
2016-09-23 22:48:37 +02:00
2018-03-02 23:51:48 +01:00
The source code for the ``ansible``
command line tools (``lib/ansible/cli/``) is `available on GitHub <https://github.com/ansible/ansible/tree/devel/lib/ansible/cli>`_.
2016-09-23 22:48:37 +02:00
.. seealso::
:ref:`developing_inventory`
2016-09-23 22:48:37 +02:00
Developing dynamic inventory integrations
:ref:`developing_modules_general`
Getting started on developing a module
:ref:`developing_plugins`
2016-09-23 22:48:37 +02:00
How to develop plugins
`Development Mailing List <https://groups.google.com/group/ansible-devel>`_
2016-09-23 22:48:37 +02:00
Mailing list for development topics
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel