rolekit.roles man page

rolekit.roles — rolekit role descripion

Role Structure

The basic structure of a role:

#from rolekit.config import ...
#from rolekit.config.dbus import ...
#from rolekit.logger import log
#from rolekit.server.decorators import ...
from rolekit.server.rolebase import RoleBase
#from rolekit.dbus_utils import ...
#from rolekit.errors import ...

class Role(RoleBase):
    # Use _DEFAULTS from RoleBase and overwrite settings or add new if needed.
    # Without overwrites or new settings, this can be omitted.
    _DEFAULTS = dict(RoleBase._DEFAULTS, **{
        "version": 1,
        "services": [ "service1" ],
        "packages": [ "package1", "@group1" ],
        "firewall": { "ports": [ "815/tcp" ],
                      "services": [ "service1" ] },
    })

    # Initialize role
    def __init__(self, name, directory, *args, **kwargs):
        super(Role, self).__init__(name, directory, *args, **kwargs)

    # Deploy code
    def do_deploy_async(self, values, sender=None):
        # Do the work here
        # In case of error raise an exception

        target = {'Role': 'testrole',
                  'Instance': self.get_name(),
                  'Description': "Test Role - %s" % self.get_name(),
                  'Wants': ['rolekit.socket'],
                  'After': ['syslog.target', 'network.target']}
        yield target

    # Decommission code
    def do_decommission_async(self, force=False, sender=None):
        # Do the work here
        # In case of error raise an exception

        yield None

To add role specific settings (properties), add the setting definition to _DEFAULTS:

        "myownsetting": "something",

Also add a check method:

    # Check own properties
    def do_check_property(self, prop, value):
        if prop == "myownsetting":
            return self.check_type_string(value)
        return False

Steps to check values of role specific properties:

1. Check value for property "prop".

2. Raise RolekitError(INVALID_VALUE, prop) in case of error.

3. Return True if a check has been done for this property.

4. Return False otherwise (no check for this property).

You can use one of the already defined check_type_X methods:

check_type_int(self, value)
check_type_string(self, value)
check_type_bool(self, value)
check_type_dict(self, value)
check_type_list(self, value)
check_type_string_list(self, value)

These methods return True for a passed test and raise in case of failure. Or write a new one if needed (see RoleBase class). Example for int type checking:

if prop == "myownprop":
  return self.check_type_int(value)
return False

Example for dict { string: [ string ] } checking:

if prop == "myownprop":
  self.check_type_dict(value)
  for x in value.keys():
    if x not in [ "key1", "key2", "key3" ]:
      raise RolekitError(INVALID_VALUE, x)
    self.check_type_string_list(value[x])
  return True
return False

Add dbus methods to be able to make the property availabe on D-Bus:

    # Static method for use in roles and instances
    #
    # Usage in roles: <class>.do_get_dbus_property(<class>, key)
    #   Returns settings as dbus types
    #
    # Usage in instances: role.do_get_dbus_property(role, key)
    #   Uses role.get_property(role, key)
    #
    # Without additional properties, this can be omitted.
    @staticmethod
    def do_get_dbus_property(x, prop):
        # Cover additional settings and return a proper dbus type.
        if prop == "myownsetting":
            return dbus.String(x.get_property(x, prop))
        raise RolekitError(INVALID_PROPERTY, prop)

    # D-Bus Property handling
    if hasattr(dbus.service, "property"):
        # property support in dbus.service

        @dbus.service.property(DBUS_INTERFACE_ROLE_INSTANCE, signature='s')
        @dbus_handle_exceptions
        def myownsetting(self):
            return self.get_dbus_property(self, "myownsetting")

To mark a settings as read-only:

    # Use _READONLY_SETTINGS from RoleBase and add new if needed.
    # Without new readonly settings, this can be omitted.
    _READONLY_SETTINGS = RoleBase._READONLY_SETTINGS + [
        "myownsetting"
    ]

There are no do_ methods for start, stop, restart and reset-error in role instances. This is handled by rolekit using the systemd target.

The do_redeploy and do_update methods can be omitted in rolekit version 0.1, they are not functional yet.

For more information about RoleBase and it's structures, please have a look at the output of pydoc rolekit.server.rolebase.

    # maximum number of instances of this role
    _MAX_INSTANCES = 1

To allow to have more than one instance of this role, set _MAX_INSTANCES to a useful maximum number. The default is 1 and will be automatically be inherited from RoleBase. The number should only be increased if it is really possible to have more than one instance of this role.

Error Codes

These are the error codes that are known to rolekit:

String Code
ALREADY_STARTED 11
NOT_STARTED 12
TOO_MANY_INSTANCES 13
NAME_CONFLICT 14
UNKNOWN_SETTING 15
READONLY_SETTING 16
COMMAND_FAILED 99
INVALID_ROLE 100
INVALID_PROPERTY 101
INVALID_VALUE 102
INVALID_OBJECT 103
INVALID_NAME 104
INVALID_SETTING 105
INVALID_LOG_LEVEL 106
INVALID_STATE 107
INVALID_INSTANCE 108
MISSING_ROLE 200
MISSING_CHECK 201
MISSING_ID 202
NOT_RUNNING 252
NOT_AUTHORIZED 253
UNKNOWN_ERROR 254

See Also

rolekit(1), rolectl(1), roled(5), rolekit.dbus(5), rolekit.roles(5), rolekit.roles.databaseserver(5), rolekit.roles.domaincontroller(5)

Notes

rolekit home page at github.com:

Authors

Thomas Woerner <twoerner@redhat.com>

Developer

Stephen Gallagher <sgallagh@redhat.com>

Developer

Miloslav Trmač <mitr@redhat.com>

Developer

Nils Philippsen <nils@redhat.com>

Developer

Referenced By

rolectl(1), roled(1), rolekit(5), rolekit.dbus(5), rolekit.roles.databaseserver(5), rolekit.roles.domaincontroller(5), rolekit.roles.memcache(5).

rolekit 0.5.2 rolekit.roles