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:

StringCode
ALREADY_STARTED11
NOT_STARTED12
TOO_MANY_INSTANCES13
NAME_CONFLICT14
UNKNOWN_SETTING15
READONLY_SETTING16
COMMAND_FAILED99
INVALID_ROLE100
INVALID_PROPERTY101
INVALID_VALUE102
INVALID_OBJECT103
INVALID_NAME104
INVALID_SETTING105
INVALID_LOG_LEVEL106
INVALID_STATE107
INVALID_INSTANCE108
MISSING_ROLE200
MISSING_CHECK201
MISSING_ID202
NOT_RUNNING252
NOT_AUTHORIZED253
UNKNOWN_ERROR254

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.1 rolekit.roles