Using Runner as a Python Module Interface to Ansible. Ansible Runner is intended to provide a directly importable and usable API for interfacing with Ansible itself and exposes a few helper interfaces. The modules center around the Runner object. The helper methods will either return an instance of this object which provides an interface to.
Python API pre 2.0 ¶. It’s pretty simple: import ansible.runner runner = ansible.runner.Runner ( modulename='ping', moduleargs=', 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 About. Ansible Runner¶ Ansible Runner is a tool and python library that helps when interfacing with Ansible directly or as part of another system whether that be through a container image interface, as a standalone tool, or as a Python module that can be imported. The goal is to provide a stable and consistent interface abstraction to Ansible. You can run the ansible-doc -l command to list all the available Ansible modules: elliot@control plays$ ansible-doc -l wc -l 3387. Currently, there are 3387 Ansible modules available, and they increase by the day! You can pass any command way you wish to run as an option to the Ansible command module.
Back in 2015 we started using Ansible at Swapps. I created a small Django application that could interface with Ansible directly, and used that to manage our infrastructure at higher level.
Back then, Ansible was in version 1.9. Ansible is written in python, so I just used the modules and started the playbooks directly. However Ansible 2.0 came out, and all of the internal API got a major revamp. Everything we had was stuck at Ansible 1.9 until we refactored the code to run on Ansible 2, which was a major change.
I was thinking on creating something that didn’t depend on the internal API structure, so we could avoid this issue in the future. After all, if we invested the resources to update to Ansible 2, it would not be good to have to do it for the next version too. Eventually, I found Ansible Runner, and everything just made sense.
Ansible Runner is, as its name implies, a tool to run Ansible. It does not care about your Ansible version, it just runs your project if you pass it a correctly structured folder. And it gets better: You can use it from the shell, but you can use it directly on Python too.
Back the, while learning about Ansible Runner, I found the official tool for which it was created: AWX. That didn’t exist back when I created our own project to give Ansible a web interface. It receives a lot of love and is constantly updated. It is a very active project.
We tried using AWX for our needs, however it lacks some features that we had added to our web interface, and while we intend to send some contributions to the project to enable said functionalities, it can take some time for it to be able to replace our internal tool. Don’t misunderstand me, AWX is AMAZING, and better architected than our own solution. It is just a matter of it not fitting our needs at the moment.
Going back to Ansible Runner, we decided to update our internal tool to use it, so we could just forget about Ansible versions and push new cool features that we are thinking of.
What do you need to run Ansible Runner?
As you can see in the documentation, you need to structure your whole playbook around certain structure, so Ansible Runner can find and start the project accordingly.
You put your environment variables, your ssh_keys and information of that kind in the env folder, inside the project you put the playbook, etc. This may look like a lot at the beginning, but it is easy to setup it up automatically if you have the information in some kind of application.
Running with Ansible Runner
Starting your playbook now is pretty easy. You can just use the following command:
And that’s it. You will receive all of the output in the console, just like you do when running the playbook directly with ansible-playbook. But we can also run the same project from Python, which in our case was HUGE:
Quite easy, right? Ansible Runner performs all of the heavy lifting for you, and you don’t have to worry about the internals anymore. Also, you can hook some callbacks in case you want to do some extra things. In our case, our module changed from having around 300 lines (initialization of everything, parsing and organization, running and results) to just this:
We send the feed we get from the runner via websockets, and we save the process after it is finished. It is quite easy to set up.
When to use Ansible Runner
If you are just starting out on Ansible, and you are wondering if you should create a web interface, Ansible Runner can help you to do so quite easily. However, make sure that your needs require so first. AWX will probably be a good fit for your needs. Or you could go with the paid version: Ansible Tower.
There are other cases where it could be interesting to use Ansible Runner instead of ansible-playbook. For example if your playbooks are all over your machine, and you are having issues understanding where are dependencies being loaded from.
Whatever be the case, Ansible is here to stay, and knowing what tools are available to you can widen your perspective when thinking about automation. That is, in the end, the final purpose for us all, right?
Topics
- Python API
- Python API pre 2.0
There are several interesting ways to use Ansible from an API perspective. You can usethe Ansible python API to control nodes, you can extend Ansible to respond to various python events, you canwrite various plugins, and you can plug in inventory data from external data sources. This documentcovers the Runner 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 Ansible Toweras 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.
The Python API is very powerful, and is how the ansible CLI and ansible-playbookare implemented. In version 2.0 the core ansible got rewritten and the API was mostly rewritten.
In 2.0 things get a bit more complicated to start, but you end up with much more discrete and readable classes:
It’s pretty simple:
The run method returns results per host, grouped by whether theycould be contacted or not. Return types are module specific, asexpressed in the About Modules documentation.:
A module can return any type of JSON data it wants, so Ansible canbe used as a framework to rapidly build powerful applications and scripts.
Python Ansible Runner Interview
The following script prints out the uptime information for all hosts:
Ansible Runner Example
Advanced programmers may also wish to read the source to ansible itself,for it uses the API (with all available options) to implement the ansiblecommand line tools (lib/ansible/cli/).
参见
Ansible Runner Python Example
- Developing Dynamic Inventory Sources
- Developing dynamic inventory integrations
- Developing Modules
- How to develop modules
- Developing Plugins
- How to develop plugins
- Development Mailing List
- Mailing list for development topics
- irc.freenode.net
- #ansible IRC chat channel