This project wraps the ansible_runner interface inside a REST API enabling ansible playbooks to be executed and queried from other platforms.
The incentive for this is two-fold;
The core of this project is ansible_runner, so first of all, a quick call out to those folks for such an awesome tool!
misc/dashboards
directory to track activity/groups
and /hosts
endpoints/api
endpoint describing each endpoint/api
content is automatically generated and has no external dependenciesSo far, testing has been mainly against Fedora (28) and the CentOS7 for the docker image. Other distros may work fine (Travis build uses Ubuntu Trusty for example!).
(see requirements.txt
for a more complete list of the python dependencies)
if in doubt, look in the misc/docker folder and build the container!
Try before you buy...assuming you have an environment that meets the python3 dependencies, simply unzip the archive and run :)
python3 ansible_runner_service.py
When you run from any directory outside of /usr, the script regards this as 'dev' mode. In this mode, all files and paths are relative to the path that you've unzipped the project into.
For 'prod' mode, a setup.py is provided. Once the package is installed and called from /usr/*/bin, the script will expect config and output files to be found in all the normal 'production' locations (see proposed file layout below)
sudo python3 setup.py install --record installed_files --single-version-externally-managed
Once this is installed, you may start the service with
ansible_runner_service
Once the service is running, you can point your browser at https://localhost:5001/api
to show which endpoints are available. Each endpoint is described along with a curl example showing invocation and output.
You may click on any row to expand the description of the API route and show the curl example. The app uses a self-signed certificate, so all examples use the -k parameter (insecure mode).
Note: It is not the intent of this API to validate the parameters passed to it. It is assumed that parameter selection and validation happen prior to the API call.
Here's a quick 'cheat sheet' of the API endpoints.
API Route | Description |
---|---|
/api | Show available API endpoints (this page) |
/api/v1/groups | List all the defined groups in the inventory |
/api/v1/groups/ |
Manage groups within the inventory |
/api/v1/hosts | Return a list of hosts from the inventory |
/api/v1/hosts/ |
Show group membership for a given host |
/api/v1/hosts/ |
Manage ansible control of a given host |
/api/v1/jobs/ |
Return a list of events within a given playbook run (job) |
/api/v1/jobs/ |
Return the output of a specific task within a playbook |
/api/v1/login | Authenticate user and provide token |
/api/v1/playbooks | Return the names of all available playbooks |
/api/v1/playbooks/ |
Query the state or cancel a playbook run (by uuid) |
/api/v1/playbooks/ |
Start a playbook by name, returning the play's uuid |
/api/v1/playbooks/ |
Start a playbook using tags to control which tasks run |
/metrics | Provide prometheus compatible statistics which describe playbook activity |
Testing to date has all been lab based, so please bear this in mind if considering using this tool for production use cases (bug reports welcome!). Playbook integration with Ceph and Gluster has been the primary focus together with the probe-disks.yml playbook. Did you spot the theme?..It's all about the storage™ :)
For example, with ceph the osd-configure.yml
playbook has been tested successfully.
The archive, downloaded from github, contains a simple playbook that just uses the bash sleep command - enabling you to quickly experiment with the API.
Use the steps below (dev mode), to quickly exercise the API
curl -k -i --user admin:admin https://localhost:5001/api/v1/login -X get
curl -k -i -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczODA3MTR9.CbTXvBum5mCq9s56wJNiMn8JLJ0UzzRdwdeOFctJtbI" https://localhost:5001/api/v1/playbooks -X GET
curl -k -i -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczODA3MTR9.CbTXvBum5mCq9s56wJNiMn8JLJ0UzzRdwdeOFctJtbI" -H "Content-Type: application/json" --data '{"time_delay": 30}' https://localhost:5001/api/v1/playbooks/test.yml -X POST
curl -k -i -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczODA3MTR9.CbTXvBum5mCq9s56wJNiMn8JLJ0UzzRdwdeOFctJtbI" https://localhost:5001/api/v1/playbooks/f39069aa-9f3d-11e8-852f-c85b7671906d -X GET
curl -k -i -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczODA3MTR9.CbTXvBum5mCq9s56wJNiMn8JLJ0UzzRdwdeOFctJtbI" https://localhost:5001/api/v1/jobs/f39069aa-9f3d-11e8-852f-c85b7671906d/events -X GET
curl -k -i -H "Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzczODA3MTR9.CbTXvBum5mCq9s56wJNiMn8JLJ0UzzRdwdeOFctJtbI" https://localhost:5001/api/v1/jobs/f39069aa-9f3d-11e8-852f-c85b7671906d/events/13-c85b7671-906d-e52d-d421-000000000008 -X GET
Obviously you'll need to change the token, play and job uuids for your run :)
Tweaking the environment:The script uses a configuration module which is accessible across the different modules within the project. There are two ways that settings in the configuration module can be overridden;
config.yaml
fileOverriding configuration at run time, lets you do quick tests like this;
$ ssh_checks=false python3 ansible_runner_service
$ target_user=root python3 ansible_runner_service
The project uses Travis CI integration to check the following;
For more info, look at the .travis.yml
file.
/etc/ansible-runner-service
/usr/share/ansible-runner-service
/var/log/ansible-runner-service.log
/usr/share/doc/ansible-runner-service
/etc/systemd/system
/usr/bin/ or /usr/local/bin