90 lines
3.4 KiB
ReStructuredText
90 lines
3.4 KiB
ReStructuredText
===============
|
|
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
|
|
|
|
|