inqbus.ocf.agents 0.11

OCF resource agents based on inqbus.ocf.generic

What do you get

This package gives you some generic OCF agent classes for PID controlled daemons:

• pidagent
• openvpn

based on the inqbus.ocf.generic framework.

The inqbus.ocf.generic framework keeps away from you the gory details you have to go into writing an OCF compatible resource agent. Powerfull base classes bring to you:

• A good test coverage of the agent code (How to test a shell script?)
• Support of the complete set of OCF exitcodes and their respective business logik
• OCF Paramter classes for integer, string, etc. values
• Predefined generic OCF handlers (meta-data, validate)
• The generation of the XML meta data is done for you automagically
• Easy addition of handlers for e.g. start/stop/status
• Inheritance of resource agents: encapsulate agent business logic and share it among similiar reasource agents

Inqbus.ocf.agents in addition brings the following functionality

• the business logic for controlling the PID file
• checking for the running state of the PID
• starting and stopping the daemon (with checking for zombies and staggered kill signals to bring a process really down if it has to die)
• checking for the PID status

in the base class PIDBaseAgent.

What is missing

We did not implement any business logic for the actions:

• notify
• demote
• promote
• master/slave
• reload

but inqbus.ocf.generic framework can represent any OCF action that is specified yet or in the future - just implement a handler for the desired action:

class MyAgent(Agent):

    def config(self):
        """
        Register my actions
        """
        self.handlers['notify'] = Handler(MyAgent.do_notify, 10)
        self.handlers['future'] = Handler(MyAgent.do_future, 10)

Installation via buildout

Build a virtual environment:

:/opt$ virtualenv --no-site-packages ocf
:/opt$ cd ocf
:/opt/ocf$ source bin/activate
(ocf):/opt/ocf$

Install the make environment buildout and initialize it:

(ocf):/opt/ocf$ easy_install zc.buildout
(ocf):/opt/ocf$ ./bin/buildout init

Create a buildout.cfg:

[buildout]
parts = app
        pidagent
        openvpn

# Buildout directories to use.
eggs-directory          = eggs

###############################################################################
# Download links for packages
# -----------------------------------------------------------------------------
# Add additional egg download sources here.
# Note that pypi.propertyshelf.com and mypypi.inqbus.de require authentication.
find-links = http://mypypi.inqbus.de/privateEggs

###############################################################################
# Extensions
# -----------------------------------------------------------------------------
# Load several extensions.
extensions = lovely.buildouthttp

[app]
recipe = z3c.recipe.scripts
eggs = inqbus.ocf.agents
interpreter = python_ocf

[openvpn]
recipe = collective.recipe.template
output = ${buildout:directory}/bin/openvpn.sh
inline =
    #!/bin/bash
    ${buildout:directory}/../bin/python ${buildout:directory}/bin/openvpn $*
mode = 755

[pidagent]
recipe = collective.recipe.template
output = ${buildout:directory}/bin/pidagent.sh
inline =
    #!/bin/bash
    ${buildout:directory}/../bin/python ${buildout:directory}/bin/pidagent $*
mode = 755

run buildout to install the package:

(ocf):/opt/ocf$ ./bin/buildout

openvpn
    A python console script, referencing the python interpreter with an
    appropriate python path.

openvpn.sh
    A bash console wrapper around the openvpn python console script.
    This is a tribute to pacemaker which calls the agent via the bash interpreter.
    These kind of wrapper scripts you have to use as agents for pacemaker.

Testing with buildout

The easiest way to test is with buildout:

$ ./bin/buildout
...
$ ./bin/nose --with-coverage
...
inqbus.ocf.agents.openvpn            91%
inqbus.ocf.agents.pidagent           83%
inqbus.ocf.agents.pidbaseagent       74%
inqbus.ocf.generic.agent             88%
inqbus.ocf.generic.container         100%
inqbus.ocf.generic.exits             84%
inqbus.ocf.generic.handlers          96%
inqbus.ocf.generic.parameter         83%

The test coverage is high. We includet the ocf-tester testcases in our test suite. Maximum testcoverage is only possible if running the tests as root since most of the tests are integration tests, which steer real unix daemons. In case of the openvpn agent a real openvpn instance is brought up.

Dispite the high level of testing there is still a portion of 10 to 26% of untested code. This code mainly attributes to the many plausability exits that are not easily tested. How should we test for a broken filesystem or a process that has become a zombie? If you think you have the answer to that questions, you are warmest welcome in the development team.

Testing with ocf-tester

Independently of the python tests pacemaker comes with the ocf-tester script. You may use the dummy_daemon that comes with inqbus.ocf.agents to test the pidagent:

:/opt/ocf/buildout$ ocf-tester -n test \
-o pid_file=/tmp/dummy_daemon.pid \
-o executable=./bin/dummy_daemon \
`pwd`/bin/pidagent.sh

0.1 (unreleased)

• Initial release

0.11 (bugfix-release)

• added "cd to config dir" paramter for openvpn agent.
• introduced ovpn_pid_dir paramter for openvpn agent.
• fixed some flaws in README.txt
• fixed that temporary files are deletetd from /tmp after tests