Actors Best Practices
Writing actors might sound a daunting task in the beginning. However, one of our main goals is to provide an easy and straight-to-the-point framework where people can intuitively write their own actors. It's also our goal to provide helpful documentation for corner cases where this isn't always possible, so we created this guide.
This document is the result of our experience writing actors for the Leapp project. Here, we put together suggestions to avoid falling into common pitfalls as well as recommendations to make this task easy.
This is a living document. We intend to update it as we progress and gain more experience writing actors.
- Identify common steps that one should take to get started writing Leapp actors.
- Document the best practices to writing actors according to our experience so far.
We have put together a short Getting Started Guide to outline the initial steps you should take on writing Leapp actors.
This guide covers some basic usage examples and is a great resource to get you started.
We have a set of conventions in Actor Developer Guidelines which should the actor developer follow to have the new actor accepted by fellow Leapp contributors.
When writing a new actor, it might be easier to test it simply by passing in some input and checking the output generated by it. This, however, will not validate the format of the data that the actor reads from the standard input and writes to standard output.
The correct approach is to use the tool snactor_runner distributed with snactor. This tool will validate the data according to the schemas passed in as arguments.
Currently, the actor itself is responsible for handling exceptional behaviours and decide if the error should be propagated or the whole workflow should be interrupted.
For instance, an actor responsible for collecting information about a certain service might rely on a tool that returns some parameters about that service. Although it's good to have this tool available, its absence shouldn't block the actor from collecting the most important information about that given service. As a result, the actor might just propagate a warning message instead of interrupting the whole workflow.
Given a complex task, it might be tempting to try to solve all of it in a single actor. However, decomposing that task into small specialized actors might bring the benefit of reusability.
For instance, if you want to migrate a database into a container, you might want to create two actors: an actor that would collect the necessary information about that database and another actor to grab that information and generate a container out of it. Then, you can use a group actor to put everything together in an orderly way.
Later, you might want to use the same scanner actor for a different task, e.g., to upgrade the database to a new version.
Leapp actors work in a very simple fashion:
- Read data from stdin.
- Process.
- Write data to stdout.
Considering that the actor's stdout is reserved, one should be careful to not print data that might make the schema validation fail. However, the prefered debugging technique of many developers is to temporarily print messages to stdout in order to decide what to do next. In Leapp actors we do this a bit differently, though. Simply write your debugging messages to stderr and the schema validation won't fail for your actor.