Developing plugins

Developing a plugin for bootstrap-vz is a fairly straightforward process, since there is very little code overhead.

The process is the same whether you create an internal or an external plugin (though you need to add some code for package management when creating an external plugin)

Start by creating an __init__.py in your plugin folder. The only obligatory function you need to implement is resolve_tasks(). This function adds tasks to be run to the tasklist:

def resolve_tasks(taskset, manifest):
    taskset.add(tasks.DoSomething)

The manifest variable holds the manifest the user specified, with it you can determine settings for your plugin and e.g. check of which release of Debian bootstrap-vz will create an image.

A task is a class with a static run() function and some meta-information:

class DoSomething(Task):
    description = 'Doing something'
    phase = phases.volume_preparation
    predecessors = [PartitionVolume]
    successors = [filesystem.Format]

    @classmethod
    def run(cls, info):
        pass

To read more about tasks and their ordering, check out the section on how bootstrap-vz works.

Besides the resolve_tasks() function, there is also the resolve_rollback_tasks() function, which comes into play when something has gone awry while bootstrapping. It should be used to clean up anything that was created during the bootstrapping process. If you created temporary files for example, you can add a task to the rollback taskset that deletes those files, you might even already have it because you run it after an image has been successfully bootstrapped:

def resolve_rollback_tasks(taskset, manifest, completed, counter_task):
    counter_task(taskset, tasks.DoSomething, tasks.UndoSomething)

In resolve_rollback_tasks() you have access to the taskset (this time it contains tasks that will be run during rollback), the manifest, and the tasks that have already been run before the bootstrapping aborted (completed).

The last parameter is the counter_task() function, with it you can specify that a specific task (2nd param) has to be in the taskset (1st param) for the rollback task (3rd param) to be added. This saves code and makes it more readable than running through the completed tasklist and checking each completed task.

You can also specify a validate_manifest() function. Typically it looks like this:

def validate_manifest(data, validator, error):
    from bootstrapvz.common.tools import rel_path
    validator(data, rel_path(__file__, 'manifest-schema.yml'))

This code validates the manifest against a schema in your plugin folder. The schema is a JSON schema, since bootstrap-vz supports yaml, you can avoid a lot of curly braces quotes:

$schema: http://json-schema.org/draft-04/schema#
title: Example plugin manifest
type: object
properties:
  plugins:
    type: object
    properties:
      example:
        type: object
        properties:
          message: {type: string}
        required: [message]
        additionalProperties: false

In the schema above we check that the example plugin has a single property named message with a string value (setting additionalProperties to false makes sure that users don’t misspell optional attributes).

Internal plugins

Internal plugins are part of the bootstrap-vz package and distributed with it. If you have developed a plugin that you think should be part of the package because a lot of people might use it you can send a pull request to get it included (just remember to read the guidelines first).

External plugins

External plugins are packages distributed separately from bootstrap-vz. Separate distribution makes sense when your plugin solves a narrow problem scope specific to your use-case or when the plugin contains proprietary code that you would not like to share. They integrate with bootstrap-vz by exposing an entry-point through setup.py:

setup(name='example-plugin',
      version=0.9.5,
      packages=find_packages(),
      include_package_data=True,
      entry_points={'bootstrapvz.plugins': ['plugin_name = package_name.module_name']},
      install_requires=['bootstrap-vz >= 0.9.5'],
      )

Beyond setup.py the package might need a MANIFEST.in so that assets like manifest-schema.yml are included when the package is built:

include example/manifest-schema.yml
include example/README.rst

To test your package from source you can run python setup.py develop to register the package so that bootstrap-vz can find the entry-point of your plugin.

An example plugin is available at https://github.com/andsens/bootstrap-vz-example-plugin, you can use it as a starting point for your own plugin.

Installing external plugins

Some plugins may not find their way to the python package index (especially if it’s in a private repo). They can of course still be installed using pip:

pip install git+ssh://git@github.com/username/repo#egg=plugin_name