Changing scaling to explicitly be scale_up_by_one and scale_down_by_one. Exception in poll_for_exceptionless_callable now passed up to MaximumAttemptsReached.

Author: Paul Breaux

f5/multi_device/cluster/__init__.py

@@ -14,7 +14,39 @@
 #
 #
 
-# TrustDomain and DeviceGroup may need to move under multi_device
+'''The classes within define the management of a cluster of BIG_IP devices.
+
+Definitions:
+    Cluster: The manager of the TrustDomain and DeviceGroup objects.
+    TrustDomain: a group of BIG-IP devices that have exchanged certificates
+                 and trust one another
+    DeviceGroup: a group of BIG-IP device that sync configuration data and
+                 failover connections.
+
+Clustering is broken down into three component parts: a cluster manager, a
+trust domain, and a device group. The cluster manager presents the external
+interface to a user for operations like create, teardown etc....
+
+To create a device service group (aka cluster) of devices, those devices
+must trust one another. This is coordinated by the TrustDomain class. Once
+those devices trust one another, a device group is created and each is added
+to the group. After this step, a cluster exists.
+
+Currently the only supported type of cluster is a 'sync-failover' cluster.
+
+ClusterManager Methods:
+
+    * create -- creates a cluster based on kwargs given by user
+    * teardown -- tears down an existing cluster
+    * scale_up_by_one -- add one device to the cluster
+    * scale_down_by_one -- remove one device from the cluster
+
+Classes:
+
+    * ClusterManager -- manages a cluster of devices with the methods above
+    * TrustDomain -- manages the trust domain for a cluster
+    * DeviceGroup -- manages the device group for a cluster
+'''
 
 from f5.sdk_exception import F5SDKError
 from f5.utils.decorators import poll_for_exceptionless_callable
@@ -24,7 +56,6 @@
 
 class ClusterError(F5SDKError):
     def __init__(self, *args, **kwargs):
-        # TODO(paul):  Place your logging 0ssmness here.
         super(ClusterError, self).__init__(*args, **kwargs)
 
 
@@ -215,7 +246,7 @@ def teardown(self):
         self.trust_domain.teardown()
         self.cluster = None
 
-    def scale_up(self, device):
+    def scale_up_by_one(self, device):
         '''Scale cluster up by one device.
 
         :param bigip: bigip object -- bigip to add
@@ -226,12 +257,12 @@ def scale_up(self, device):
             msg = 'The number of devices to cluster is not supported.'
             raise ClusterNotSupported(msg)
         print('Scaling cluster up by one device...')
-        self.trust_domain.scale_up(device)
-        self.device_group.scale_up(device)
+        self.trust_domain.scale_up_by_one(device)
+        self.device_group.scale_up_by_one(device)
         self.cluster.devices.append(device)
         self.device_group.ensure_all_devices_in_sync()
 
-    def scale_down(self, device):
+    def scale_down_by_one(self, device):
         '''Scale cluster down by one device.
 
         :param device: ManagementRoot object -- device to delete
@@ -242,8 +273,8 @@ def scale_down(self, device):
             msg = 'The number of devices to cluster is not supported.'
             raise ClusterNotSupported(msg)
         print('Scaling cluster down by one device...')
-        self.device_group.scale_down(device)
-        self.trust_domain.scale_down(device, self.device_group)
+        self.device_group.scale_down_by_one(device)
+        self.trust_domain.scale_down_by_one(device, self.device_group)
         self.cluster.devices.remove(device)
         self.device_group.ensure_all_devices_in_sync()
 
@@ -341,7 +372,7 @@ def teardown(self):
         pollster(self._check_devices_active_licensed)()
         pollster(self._check_all_devices_in_sync)()
 
-    def scale_up(self, device):
+    def scale_up_by_one(self, device):
         '''Scale device group up by one device
 
         :param device: ManagementRoot object -- device to add to device group
@@ -357,7 +388,7 @@ def scale_up(self, device):
         self.devices.append(device)
         self.ensure_all_devices_in_sync()
 
-    def scale_down(self, device):
+    def scale_down_by_one(self, device):
         '''Scale device group down by one device
 
         :param device: ManagementRoot object -- device to delete from device
@@ -628,7 +659,7 @@ def teardown(self):
             self._populate_domain()
         self.domain = {}
 
-    def scale_up(self, device):
+    def scale_up_by_one(self, device):
         '''Scale up trust domain by one device.
 
         :param device: ManagementRoot object -- device to scale up
@@ -638,7 +669,7 @@ def scale_up(self, device):
         self._add_trustee(device)
         pollster(self.validate)()
 
-    def scale_down(self, device, device_group_object=None):
+    def scale_down_by_one(self, device, device_group_object=None):
         '''Scale down trust domain by one device.
 
         :param device: ManagementRoot object -- device to scale down
@@ -662,8 +693,9 @@ def _add_trustee(self, device):
     def _remove_trustee(self, device, device_group_object=None):
         '''Remove a trustee from the trust domain.
 
-        If this is called as part of scale_down, the device being scaled must
-        remove the members of its device group before removing trusted devices
+        If this is called as part of scale_down_by_one, the device being scaled
+        must remove the members of its device group before removing trusted
+        devices. This is optional.
 
         :param device: MangementRoot object -- device to remove
         '''

f5/multi_device/cluster/test/test_cluster_manager.py

@@ -154,15 +154,15 @@ def test_scale_up_too_many_devices(ClusterManagerCreateNew, BigIPs):
         devices=mock_bigips, device_group_name='name',
         device_group_partition='part', device_group_type='sync-failover')
     mock_bigip1 = mock.MagicMock()
-    cm.scale_up(mock_bigip1)
+    cm.scale_up_by_one(mock_bigip1)
     mock_bigip2 = mock.MagicMock()
-    cm.scale_up(mock_bigip2)
+    cm.scale_up_by_one(mock_bigip2)
     mock_bigip3 = mock.MagicMock()
-    cm.scale_up(mock_bigip3)
+    cm.scale_up_by_one(mock_bigip3)
     mock_bigip4 = mock.MagicMock()
-    cm.scale_up(mock_bigip4)
+    cm.scale_up_by_one(mock_bigip4)
     with pytest.raises(ClusterNotSupported) as ex:
-        cm.scale_up(mock.MagicMock())
+        cm.scale_up_by_one(mock.MagicMock())
     assert sorted(cm.cluster.devices) == sorted(mock_bigips)
     assert 'The number of devices to cluster is not supported.' == \
         ex.value.message
@@ -174,10 +174,10 @@ def test_scale_down_cluster_not_supported(ClusterManagerCreateNew, BigIPs):
     cm.create(
         devices=mock_bigips, device_group_name='name',
         device_group_partition='part', device_group_type='sync-failover')
-    cm.scale_down(mock_bigips[0])
+    cm.scale_down_by_one(mock_bigips[0])
     assert cm.cluster.devices == mock_bigips
-    cm.scale_down(mock_bigips[0])
+    cm.scale_down_by_one(mock_bigips[0])
     with pytest.raises(ClusterNotSupported) as ex:
-        cm.scale_down(mock_bigips[0])
+        cm.scale_down_by_one(mock_bigips[0])
     assert 'The number of devices to cluster is not supported.' == \
         ex.value.message

f5/multi_device/cluster/test/test_device_group.py

@@ -104,7 +104,7 @@ def test_scale_up_device_already_in_group(DeviceGroupCreateNew, BigIPs):
     mock_names_in_group.return_value = ['test']
     dg._get_device_names_in_group = mock_names_in_group
     with pytest.raises(DeviceGroupOperationNotSupported) as ex:
-        dg.scale_up(mock_bigip)
+        dg.scale_up_by_one(mock_bigip)
     assert "Device: 'test' is already in device group" == ex.value.message
 
 
@@ -119,7 +119,7 @@ def test_scale_down_device_not_in_group(DeviceGroupCreateNew, BigIPs):
     mock_names_in_group.return_value = ['no_match']
     dg._get_device_names_in_group = mock_names_in_group
     with pytest.raises(DeviceGroupOperationNotSupported) as ex:
-        dg.scale_down(mock_bigip)
+        dg.scale_down_by_one(mock_bigip)
     assert "Device: 'test' is not in device group" == ex.value.message
 
 

f5/utils/decorators.py

@@ -15,15 +15,13 @@
 #
 
 from functools import wraps
-from future.utils import raise_from
 import time
 
 from f5.utils.util_exceptions import UtilError
 
 
 class MaximumAttemptsReached(UtilError):
     def __init__(self, *args, **kwargs):
-        # TODO(paul):   Add logging here!
         super(MaximumAttemptsReached, self).__init__(*args, **kwargs)
 
 
@@ -43,7 +41,7 @@ def poll(*args, **kwargs):
                 return callable(*args, **kwargs)
             except Exception as ex:
                 if attempt == attempts-1:
-                    raise_from(MaximumAttemptsReached(), ex)
+                    raise MaximumAttemptsReached(ex)
                 time.sleep(interval)
                 continue
     return poll

test/functional/cluster/test_cluster.py

@@ -76,6 +76,22 @@ def teardown_cluster():
     request.addfinalizer(teardown_cluster)
 
 
+def test_existing_failover_cluster(BigIPSetup):
+    a, b, = BigIPSetup
+    bigip_list = [a, b]
+
+    cm = ClusterManager(
+        devices=bigip_list,
+        device_group_name=DEVICE_GROUP_NAME,
+        device_group_partition=PARTITION,
+        device_group_type='sync-failover'
+    )
+    assert cm.cluster.devices == bigip_list
+    assert cm.cluster.device_group_name == DEVICE_GROUP_NAME
+    assert cm.cluster.device_group_type == 'sync-failover'
+    assert cm.cluster.device_group_partition == PARTITION
+
+
 def test_new_failover_cluster_two_member(BigIPSetup):
     a, b, c = BigIPSetup
     bigip_list = [a, b]