Using the Services Framework to Implement Your Charm’s Intent

The ServiceManager

The primary driver of the Services Framework is the ServiceManager() class. It has one method, manage() which causes it to inspect all of its defined services and fire callbacks when their conditions are met. It has become traditional to put the creation of this object in a file under the hooks/ directory, called services.py with the manage() call inside an if __name__ == '__main__': block.

Since the question of which hook is being called is less important now, we can wire up nearly all of the events we expect to receive to this services.py file:

ubuntu@myhost:~/mynewcharm/hooks/$ ls -l
-rw-rw-r-- 1 ubuntu ubuntu 5983 Feb 24 17:27 actions.py
-rw-rw-r-- 1 ubuntu ubuntu 1073 Feb 24 17:27 my_helpers.py
drwxrwxr-x 6 ubuntu ubuntu 4096 Feb 24 17:27 charmhelpers/
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 config-changed -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 install -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 nrpe-external-master-relation-joined -> services.py*
-rw-rw-r-- 1 ubuntu ubuntu 1156 Feb 24 17:27 services.py
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 start -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 stop -> services.py*
drwxrwxr-x 2 ubuntu ubuntu 4096 Jan 21 09:54 tests/
lrwxrwxrwx 1 ubuntu ubuntu 2838 Jan 21 09:54 upgrade-charm*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 webservice-relation-broken -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 webservice-relation-changed -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 webservice-relation-departed -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 webservice-relation-joined -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 website-relation-broken -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 website-relation-changed -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 website-relation-departed -> services.py*
lrwxrwxrwx 1 ubuntu ubuntu    8 Jan 21 09:54 website-relation-joined -> services.py*

Notice that we’ve aimed symbolic links at services.py for all of the relation hooks, the install and config-changed hooks, as well as the start and stop hooks. The only hook we haven’t used the Services Framework for is upgrade-charm. This is because the upgrade-charm hook is far more difficult to write in a declarative style, depending as it does on the path between two particular versions of the charm.

Actions

All of the work done on the unit is bundled into functions called actions. In our data_ready section above, we called render_template(), passing in the source template name and destination path. This action generator actually exists in the services.helpers module, along with other action functions to do things like start and stop services.

But let’s take a look at the simpler install_packages() action for now:

def install_packages(service_name):
    if 'hold' in config['package_status']:
        fetch.apt_hold(service_name)
    return fetch.apt_install(service_name)

This function is simple enough and trivially idempotent, so we just let it run every time an event fires. It has its own self-contained logic to determine if it’s meant to put the package on hold.

It also trusts that the service_name parameter will hold the package name. This works in our case as we set the service entry in the ServiceManager()’s data structure to squid3, and that gets passed in to all actions.

More Elaborate Actions

The built-in render_template() action makes use of more advanced features, which it gained by subclassing the ManagerCallback class. We were able to instantiate it with the template location and output path, and the template context dictionary was pre-populated with all of the information that was checked in the required_data section. This gave our templates access to all of the values from the charm configuration (thanks to the RequiredConfig object) and the website relation (thanks to the RelationContext object).

Required Data

The real magic of the Services Framework, though, comes from its abstraction of the event/hook model. When we can specify the config and relation data we’re waiting for, we don’t need to fire our actions until they’re ready. The way this is achieved by the ServiceManager() is surprisingly elegant.

All of the items in the required_data list are either dicts or subclasses of dict. If any one of these objects is “falsey”², then the service is not ready and none of the data_ready actions fire.³ This allows us to write our own __bool__() methods to let our code decide if our desired conditions are met.

Apparmor Won’t Always Work in an LXC (yet!)

Writing a custom required data object can be simple. While working on the Apache2 subordinate charm, we discovered that apparmor didn’t behave the way we expected when we deployed our charms in LXC containers on our laptops. To work around this, we made a custom NotLxc() object to put in the required_data list for the apparmor-related actions.

It went a little like this:

class NotLxc(dict):
    """ In LXC containers, the `/run/container_type` file will
    contain the string 'lxc', and outside containers the file
    may not exist at all. """

    def __init__(self):
        try:
            with open('/run/container_type') as f:
                self['container_type'] = f.read().strip()
        except IOError:
            self['container_type'] = 'bare metal'

    def __bool__(self):
        return 'lxc' not in self['container_type']

    __nonzero__ = __bool__

Making custom objects like this is simple:

1. Subclass dict, and put some values in self['something'] to flesh out the dictionary
2. Override __bool__() and __nonzero__() to define your own “is it ready?” condition, instead of the default “Is this dict empty?” behaviour.

Now not only do we have a NotLxc class that can prevent actions from running on containers that don’t support them, but we also have placed that container_type variable into the context for the render_template() action. And most of the actual work here was spent handling errors from open()!

The Future of the Framework

The Services Framework is ready right now for you to make writing charms easier, but it has some quirks that you should be aware of.

The one you notice most as your charm grows in complexity is that the framework is written with a sort of “client-side” execution model. The provided_data section (which we didn’t cover here) unconditionally sends all its information to its RelationContext() objects before it considers the required_data. It’s intended to announce information and collect the response from the other side, and then take action based on that.

So the Services Framework doesn’t help the other side of this conversation as much. Writing the “server” side of a relation protocol requires you to call the standard Charm Helpers hookenv.relation_set() function in your actions. It’s not a hardship, by any means, but it definitely feels like a missed opportunity. Doing this in a way that fits the framework best seems to involve making custom notify_relation_with_data() actions to send the responses, and putting them in special services inside your ServiceManager() list.

The New Charm Helpers Framework

Fortunately the authors of the Services Framework are keenly aware of such impedance mismatches, and have been working on refinements to the system. The Juju Big Data Development team have been working on the next version of this framework, which they’re calling The Charm Helpers Framework.

The new framework is exciting, but have no fear: all of the effort put into writing or converting charms to use the existing Services Framework will be rewarded even with the new system. The Charm Helpers Framework is merely a simpler and more flexible implementation of the same coding practices. Both systems help you write your charm hooks in the same way: the way you likely already tend to think about them.

1. If you’re not familiar, a “reverse” proxy is one that sits in front of a particular Web site and caches and/or load-balances requests from all over the Internet. This is because the first “forward” Web caches were originally used to speed up a local network’s outbound access to public Web pages.↩
2. Numerically zero items or empty collection types fail if tests in Python, even if they’re not strictly the False value. These are called “falsey” values in the Python community.↩
3. It’s not uncommon to add values to a template’s context dictionary by simply dropping a dict in to required_data, and an empty dict is a quick way to disable a service unconditionally.↩