===============
loopabull-tasks
===============

`loopabull`_ is an event loop driven `Ansible`_ `playbook`_ execution engine.

In other words, it triggers Ansible playbooks automatically when receiving a
corresponding `fedmsg`_ message.

This repository stores the ansible playbooks and their related scripts used by
the `Fedora`_ `Infrastructure`_ team.


Adding a new task
-----------------

Adding a new task to loopabull is quite easy.

* Figure out which fedmsg topic you want to trigger off
* Create a playbook named after the topic
* Create a role doing the action you want to have triggered of this topic
* Configure loopabull to listen to this topic
* Push the new loopabull configuration

For example, let's run a small/dummy python script everytime a koji build
finished in staging.

The topic we want to trigger of is thus: ``org.fedoraproject.stg.buildsys.build.state.change``,
so we go and edit the playbook: ``playbooks/org.fedoraproject.stg.buildsys.build.state.change.yml``
in this repository and add a `debug` role that has one variable: the message
received via fedmsg `msg`.
Then add a ``debug`` role in ``playbooks/roles/debug``. Make that role install
your python script, call it with a certain environment variable and print
the output of the script for debugging.

Then, on the infrastructure's ansible repository, configure loopabull to listen
to this topic (line 70):
https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/playbooks/groups/loopabull.yml?id=4b053dd68cc12e1823516eec481fab04f9b9166b#n70

Finally, run the ansible playbook deploying this change:

::

    ansible-playbook /srv/web/infra/ansible/playbooks/groups/loopabull.yml -t loopabull


.. note:: you may have to restart things on loopabull's side:

    ::

        systemctl restart loopabull loopabull@1 loopabull@2 loopabull@3 loopabull@4 loopabull@5


For every change made to this repository (for example when fixing typos, bugs
or making improvements), the ``playbooks/groups/loopabull.yml`` playbook from
the Fedora infrastructure's ansible repo will need to be run so the underlying
clone of this repo on the system gets updated.


Good Practice
-------------

* Keep in mind that a playbook run locally and can be ran by multiple workers
  simultaneously, therefore it is advised to keep all blocking tasks out of
  this repository (for example: avoid installing packages, install them
  via the ``playbooks/groups/loopabull.yml`` playbook in infra's ansible repo.)

* Do not have your script return a non-zero error code. If a playbook fails
  (returns a non-zero return code) loopabull will stop the worker. So use the
  non-zero return code carefully so as to not kill all the workers and break
  loopabull

* Passing JSON blobs to a shell script can be tricky, especially with regards
  to the quotes used. Imaging a fedmsg messages containing itself some JSON
  fields (we do have some), you quickly end up with a mix of single-quote
  ``'`` and double-quotes ``"``. The proper way to pass the message to the
  script avoiding issues with quotes is to use: ``{{ msg | to_json | quote }}``
  (note the lack of quotes surrounding this, ``| quote`` takes care of adding
  them).



.. _Ansible: https://github.com/ansible/ansible
.. _fedmsg: http://www.fedmsg.com/en/latest/
.. _Fedora: https://getfedora.org/
.. _Infrastructure: https://fedoraproject.org/wiki/Infrastructure
.. _loopabull: https://github.com/maxamillion/loopabull
.. _playbook: http://docs.ansible.com/ansible/playbooks.html