New subscriber API in Foreman 2.0 (was: foreman_hooks)


Foreman 2.0 will be coming out with a new subscriber API. It allows users and devs to create Foreman plugins with Ruby code that is called after there is an event in Foreman. After some experience with foreman_hooks plugin which provides similar feature with shell scripts, we have decided to start small:

  • host is created, updated, deleted, enters or exits build state
  • hostgroup is created, updated, deleted

Actions do happen via Rails instrumentation API from after_commit ActiveRecord callback and not via validators which prevents plugins from canceling transactions or performing other calls when transaction hasn’t been committed yet.

Foreman 2.0 is the first phase when we want to give our users and devs the tool, in the upcoming weeks we would like to introduce these plugins currently in prototypes:

  • foreman_webhooks - Github-like stype configurable webook caller
  • foreman_redishooks - simple publisher via Redis Pub-Sub protocol with example receiver written in Ruby and/or Python for those who prefer more foreman_hooks experience

We expect one or both these plugins to be part of the foreman core plugin ecosystem after the 2.0 release. Let me know what you think and also what evens you would like to see to be published.



Thanks @lzap for sharing this! Do you know, if there’s some easy migration path for people, who already use foreman_hooks planned and if not, how much effort that would be? From your writeup I understood, the first actions users will be able to hook to, are only around hosts and hostgroups. What is the reason for not exposing the same for all models? Looking forward to see the first subscriber plugin.

I was hoping to have one, however we have decided to learn from the mistakes and design the new API in the cleanest possible way. Specifically the payload is now just a record id/name in contrast to the original solution (rendered HAML, full JSON). Also, hooks are now explicit and we don’t want to allow to attach to every possible active record event.

In short, I believe it’s not feasible to create compatibility layer. Although this would be probably technically possible, I don’t want to maintain such a layer in the future. Therefore what I suggest is to invest the time in improving the core and plugins, possibly documentation and keep the foreman_hooks as a viable option for couple of releases going forward in “best effort” or “status quo” mode. Let’s leverage the power of open source, if there is anybody interested in keeping foreman_hooks alive we will welcome contributions.

More than that, I think we should consider supporting only one plugin and I believe it should be the webhooks one which is the “de facto” standard in the industry. Therefore I suggest to promote it to the theforeman github organization while I can still push my “prototype” plugin into my own github just to serve as an example of how to write a simple hooks plugins. We should advertise webhooks as the only supported integration way.

My ask would be to let the two plugins be installed at the same time. If we do that, i think users will be able to transition to a better API.

We can do this, actually they would enable tree: foreman_hooks (the legacy one), webhooks + redis.