high-level API: add ResourceGroup object

This new class represents a LINSTOR resource group and makes it
accessible in the high level API. It allows what one would expect,
including creating, modifying, deleting resource groups and creating new
Resource objects from a ResourceGroup.

Important: This modifies the semantic of Resource.from_resource_group().
This allows it to follow the semantic used in the Resource object (as
well as ResourceGroup). We don't have that many users already using
resource groups. Overall this makes it a lot more consistent with the
rest of the HL API.

Author: rck

doc/introduction.rst

@@ -37,33 +37,40 @@ There are 2 error classes that will or can be thrown from a :py:class:`~.Linstor
 
     Linstor error indicating a network/connection error.
 
+Code Samples Using the High-Level ResourceGroup API
+---------------------------------------------------
 
-Code Samples Using the High-Level Resource API
-----------------------------------------------
-
-In this section we describe methods that are typically used by plugin developers.
+In this section we describe methods that are typically used by plugin developers. Using resource groups is the
+prefered way.
 
 Create a resource N-times redundant
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A code sample on how to create a resource "foo", with a size of 20MiB 3-times redundant.
-Usually that code is executed in a "create" call in a plugin.
+A code sample on how to create a resource "foo", with a size of 20MiB. This first creates (or reuses) a
+resource group named threeSSD, that uses a fast SSD pool and places resources 3-times redundant.  Usually that
+code is executed in a "create" call in a plugin.
 
 .. code-block:: python
 
   import linstor
-  foo = linstor.Resource('foo', uri='linstor://192.168.0.42')  # by default uri is localhost
-  foo.volumes[0] = linstor.Volume('20 MiB')
-  foo.placement.redundancy = 3
-  foo.autoplace()
+  ssd_grp = linstor.ResourceGroup('threeSSD', uri='linstor://192.168.0.42')  # by default uri is localhost
+  ssd_grp.redundancy = 3  # only if used for the first time
+  ssd_grp.storage_pool = 'myssdpool'  # only if used for the first time
+  foo = ssd_grp.create_resource('foo', ['20 MiB'])
+
+Code Samples Using the High-Level Resource API
+----------------------------------------------
+
+In this section we describe methods that are typically used by plugin developers after a resource is created
+from a resource group, or if a resource already exists.
 
 Resizing an existing resource/volume
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
   import linstor
-  foo = linstor.Resource('foo')
+  foo = linstor.Resource('foo')  # or from a .create_resource() of a resource group
   foo.volumes[0].size = linstor.Volume('30 MiB')
   # resize again
   foo.volumes[0].size += 10 * 1024 * 1024

doc/linstor.rst

@@ -19,6 +19,14 @@ linstor.resource module
     :undoc-members:
     :show-inheritance:
 
+linstor.resourcegroup module
+----------------------------
+
+.. automodule:: linstor.resourcegroup
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 linstor.kv module
 -------------------------
 

linstor/__init__.py

@@ -4,6 +4,7 @@
 from .linstorapi import Linstor, MultiLinstor
 from .resource import Resource, Volume
 from .kv import KV
+from .resourcegroup import ResourceGroup
 from .config import Config
 from .responses import StoragePoolDriver
 from .linstorapi import ResourceData

linstor/resource.py

@@ -36,10 +36,18 @@ def to_unicode(cls, t):
 class _Client(object):
     def __init__(self, uris, timeout=300, keep_alive=False):
         # external properties
-        self.uri_list = linstor.MultiLinstor.controller_uri_list(uris)  # type: list[str]
+        self._uri_list = linstor.MultiLinstor.controller_uri_list(uris)  # type: list[str]
         self.timeout = timeout
         self.keep_alive = keep_alive
 
+    @property
+    def uri_list(self):
+        return self._uri_list
+
+    @uri_list.setter
+    def uri_list(self, uri_list):
+        raise linstor.LinstorReadOnlyAfterSetError()
+
 
 class _Placement(object):
     def __init__(self, redundancy=2):
@@ -232,18 +240,21 @@ def __repr__(self):
         return "Resource({n}, {h})".format(n=self, h=self.client.uri_list)
 
     @classmethod
-    def from_resource_group(cls, linstor_controllers, resource_group_name, resource_name, vlm_sizes):
+    def from_resource_group(cls, uri, resource_group_name, resource_name, vlm_sizes,
+                            timeout=300, keep_alive=False):
         """
         Spawns a new resource definition from the given resource group.
 
-        :param str linstor_controllers: string of possible linstor controllers, feeded to .controller_uri_list
+        :param str uri: A list of controller addresses.
+         e.g: ``linstor://localhost,10.0.0.2``, ``linstor+ssl://localhost,linstor://192.168.0.1``
         :param str resource_group_name: Name of the resource group
         :param str resource_name: Name of the new resource definition
         :param list[str] vlm_sizes: String list of volume sizes e.g. ['128Mib', '1G']
         :return: Resource object of the newly created resource definition
         :rtype: Resource
         """
-        with linstor.MultiLinstor(linstor.MultiLinstor.controller_uri_list(linstor_controllers)) as lin:
+        c = _Client(uri)
+        with linstor.MultiLinstor(c.uri_list, timeout, keep_alive) as lin:
             result = lin.resource_group_spawn(
                 resource_group_name,
                 resource_name,
@@ -258,7 +269,7 @@ def from_resource_group(cls, linstor_controllers, resource_group_name, resource_
                     )
                 )
 
-            return Resource(resource_name, uri=linstor_controllers)
+            return Resource(resource_name, uri=uri)
         return None
 
     def _set_properties(self):