src/ceph/doc/dev/ceph-volume/plugins.rst

   1 .. _ceph-volume-plugins:
   2
   3 Plugins
   4 =======
   5 ``ceph-volume`` started initially to provide support for using ``lvm`` as
   6 the underlying system for an OSD. It is included as part of the tool but it is
   7 treated like a plugin.
   8
   9 This modularity, allows for other device or device-like technologies to be able
  10 to consume and re-use the utilities and workflows provided.
  11
  12 Adding Plugins
  13 --------------
  14 As a Python tool, plugins ``setuptools`` entry points. For a new plugin to be
  15 available, it should have an entry similar to this in its ``setup.py`` file:
  16
  17 .. code-block:: python
  18
  19     setup(
  20         ...
  21         entry_points = dict(
  22             ceph_volume_handlers = [
  23                 'my_command = my_package.my_module:MyClass',
  24             ],
  25         ),
  26
  27 The ``MyClass`` should be a class that accepts ``sys.argv`` as its argument,
  28 ``ceph-volume`` will pass that in at instantiation and call them ``main``
  29 method.
  30
  31 This is how a plugin for ``ZFS`` could look like for example:
  32
  33 .. code-block:: python
  34
  35     class ZFS(object):
  36
  37         help_menu = 'Deploy OSDs with ZFS'
  38         _help = """
  39     Use ZFS as the underlying technology for OSDs
  40
  41     --verbose   Increase the verbosity level
  42         """
  43
  44         def __init__(self, argv):
  45             self.argv = argv
  46
  47         def main(self):
  48             parser = argparse.ArgumentParser()
  49             args = parser.parse_args(self.argv)
  50             ...
  51
  52 And its entry point (via ``setuptools``) in ``setup.py`` would looke like:
  53
  54 .. code-block:: python
  55
  56         entry_points = {
  57             'ceph_volume_handlers': [
  58                 'zfs = ceph_volume_zfs.zfs:ZFS',
  59             ],
  60         },
  61
  62 After installation, the ``zfs`` subcommand would be listed and could be used
  63 as::
  64
  65     ceph-volume zfs