fink plugin mechanism

The previous chapter gave an overview on the fink plugin system so please make sure that you have read through that one. This section goes into more detail in how the fink plugin mechanism works. So you can customize plugins or even write new ones.

fink plugins are standard python packages which are installed separately. How to do this is covered in the previous chapter plugin overview. To understand how the plugin mechanism works one must know about the fink lifecycle which is covered in the next section.

If a fink command is entered on the command line things are processed in the following order:

  • Python interpreter loads the fink package
  • CLI options and arguments are parsed
  • we check if any relevant plugins are installed (details in plugin entry_points)
  • relevant plugins are loaded and check if they comply to fink plugin structure.
  • register() function of each plugin is called.
  • then the fink lifecycle is executed
  • each lifecycle step fires an event which we call signal

Anatomy of a plugin

Each fink plugin must implement register() and deregister() functions to be a valid fink-plugin that can be used. Note how the register() function connects the plugin function say_hello with the initialized lifecycle step. deregister() just disconnects the plugin functionality from the fink lifecycle.

def say_hello(context):
    """
    :param context: The boto_session, etc.. say_hello plugin needs the 'user'
    """
    print('MoinMoin %s!' % context.get('user', 'to you'))

...

def register():
    """Please be very specific about when your plugin needs to run and why.
    E.g. run the sample stuff after at the very beginning of the lifecycle
    """
    fink_signals.initialized.connect(say_hello)
    fink_signals.finalized.connect(say_bye)


def deregister():
    fink_signals.initialized.disconnect(say_hello)
    fink_signals.finalized.disconnect(say_bye)

Handing in information to your plugin functions. Look into fink.fink_signals for details.

def my_plug_function(params):
    """
    :param params: context, config (context - the env, user, _awsclient, etc..
                   config - The stack details, etc..)
    """
    context, config = params
    # implementation here
    ...

All fink lifecycle steps provide the (context, config) tuple besides initialized and finalized. These two only provide the context.

The same lifecycle & signals mechanism applies to fink hooks. So if you ever wondered how fink hooks are work - now you know.

Overview of the fink lifecycle

The fink lifecycle is the essential piece of the fink tool core. It is like the clockwork of a watch. The fink lifecycle makes sure that everything is executed in the right order and everything works together like commands, hooks, plugins, etc.

The fink lifecycle is generic. This means the fink lifecycle is the same for each and every fink tool. But it is possible that a tool does not need a certain lifecycle step to it just skips it. For example there is no bundling for cloud(, yet?).

The coarse grained fink lifecycle looks like that:

fink_lifecycle

If during processing of a lifecycle an error occurs then the processing stops.

List of fink signals

The list of fink signals you can use in plugins or hooks:

  • initialized - after reading arguments and context
  • config_read_init
  • config_read_finalized
  • check_credentials_init
  • check_credentials_finalized
  • lookup_init
  • lookup_finalized
  • config_validation_init
  • config_validation_finalized
  • bundle_pre - we need this signal to implement the prebundle-hook
  • bundle_init
  • bundle_finalized
  • command_init
  • command_finalized
  • error
  • finalized

The order of this list also represents the order of the lifecycle steps with in the fink lifecycle.

Developing plugins

If you want to develop a plugin to integrate some service or to optimize the configuration for your environment we recommend that you “fork” the say_hello plugin so you have the right structure and start from there.

If you need help developing your plugin or want to discuss your plans and get some feedback please don’t be shy. The SRE squad is here to help.

Testing a plugin

Testing a fink plugin should be easy since its code is decoupled from fink core. It is a good practice to put the tests into the tests folder. Also please prefix all your test files with test_ in this way pytest can pick them up. Please make sure that your plugin test coverage is on the save side of 80%.