Fixing opt-in for cluster tests and trust domain sync

Issues:
Fixes #456 and #460

Problem:
Developers must be able to opt-in to the cluster tests, since they
require a set of at least four bigip devices.

Also, a trust domain is implemented as a device group on the bigip
devices, and we must be able to sync that group when we add members to
the trust domain.

Analysis:
Used pytest.mark.skip to skip cluster tests unless a user has set a key
of 'run_cluster_tests' and a value of JSON/YAML truthiness.

The trust domain now instantiates a device group manager to sync to that
group when adding devices to the trust domain. This is a part of the
validation process in the device group and the trust domain.

Tests:
All unit and functional tests pass

Author: Paul Breaux

f5/multi_device/cluster/__init__.py

@@ -34,18 +34,12 @@
 
 Currently the only supported type of cluster is a 'sync-failover' cluster.
 
-ClusterManager Methods:
+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
-
-Usage:
+Examples:
 
 There are two major use-cases here:
 
@@ -58,9 +52,6 @@
                             device_group_type='sync-failover',
                             device_group_partition='Common'
                         )
-        new_bigip_device = ManagementRoot(...)
-        cluster_mgr.scale_up_by_one(new_bigip_device)
-        list_of_bigips.append(new_bigip_device)
         assert cluster_mgr.cluster.devices == list_of_bigips
 
     * Create a new cluster and manage it:
@@ -178,35 +169,3 @@ def teardown(self):
         self.device_group.teardown()
         self.trust_domain.teardown()
         self.cluster = None
-
-    def scale_up_by_one(self, device):
-        '''Scale cluster up by one device.
-
-        :param bigip: bigip object -- bigip to add
-        :raises: ClusterNotSupported
-        '''
-
-        if len(self.cluster.devices) == 8:
-            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_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_by_one(self, device):
-        '''Scale cluster down by one device.
-
-        :param device: ManagementRoot object -- device to delete
-        :raises: ClusterNotSupported
-        '''
-
-        if len(self.cluster.devices) < 3:
-            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_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()

f5/multi_device/cluster/test/test_cluster_manager.py

@@ -147,7 +147,7 @@ def test_teardown_cluster(ClusterManagerCreateNew, BigIPs):
     assert cm.cluster is None
 
 
-def test_scale_up_too_many_devices(ClusterManagerCreateNew, BigIPs):
+def itest_scale_up_too_many_devices(ClusterManagerCreateNew, BigIPs):
     cm = ClusterManagerCreateNew
     mock_bigips = BigIPs
     cm.create(
@@ -168,7 +168,7 @@ def test_scale_up_too_many_devices(ClusterManagerCreateNew, BigIPs):
         ex.value.message
 
 
-def test_scale_down_cluster_not_supported(ClusterManagerCreateNew, BigIPs):
+def itest_scale_down_cluster_not_supported(ClusterManagerCreateNew, BigIPs):
     cm = ClusterManagerCreateNew
     mock_bigips = BigIPs
     cm.create(

f5/multi_device/device_group.py

@@ -1,3 +1,4 @@
+# coding=utf-8
 # Copyright 2016 F5 Networks Inc.
 
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,24 +15,76 @@
 #
 #
 
-'''Class for managing a DeviceGroup for a set of BIG-IP devices.'''
+'''Class for managing a DeviceGroup for a set of BIG-IP® devices
+
+Managing a device group for clustering is an event-driven process. Please
+use the methods here to control that process. The fundamental idea is that
+any action should have an observable outcome. Adding a device to the device
+group should have a consequence for each member of the device group,
+including the newly added member.
+
+Examples:
+
+There are two major use-cases here:
+
+    * Manage an existing device group:
+
+        list_of_bigips = [ManagementRoot(...), ManagementRoot(...)]
+        device_group = DeviceGroup(
+                            devices=list_of_bigips,
+                            device_group_name='my_cluster',
+                            device_group_type='sync-failover',
+                            device_group_partition='Common'
+                        )
+        device_group.ensure_all_devices_in_sync()
+
+    * Create a new device group and manage it:
+
+        list_of_bigips = [ManagementRoot(...), ManagementRoot(...)]
+        device_group = DeviceGroup()
+        device_group.create(
+                        devices=list_of_bigips,
+                        device_group_name='my_cluster',
+                        device_group_type='sync-failover',
+                        device_group_partition='Common'
+                    )
+        device_group.ensure_all_devices_in_sync()
+
+Methods:
+
+    * create -- create a device group from a list of devices
+    * teardown -- teardown a device group, but leave the trust domain intact
+    * validate -- ensure a device group is in the proper state based on inputs
+    * manage_extant -- manage an existing device group
+
+'''
 
 from f5.multi_device.exceptions import DeviceGroupNotSupported
-from f5.multi_device.exceptions import DeviceGroupOperationNotSupported
 from f5.multi_device.exceptions import MissingRequiredDeviceGroupParameter
 from f5.multi_device.exceptions import UnexpectedDeviceGroupDevices
 from f5.multi_device.exceptions import UnexpectedDeviceGroupState
 from f5.multi_device.exceptions import UnexpectedDeviceGroupType
 
 from f5.multi_device.utils import get_device_info
-from f5.multi_device.utils import get_device_names_to_objects
 from f5.multi_device.utils import pollster
 
 
 class DeviceGroup(object):
-    '''Class to manage device service group.'''
+    '''Class to manage device service group
+
+    For the non-public methods, there are a few flavors of behavior:
+    get, check, and ensure. A 'get' retrieves some info from the device
+    without any assumptions about that info. A 'check' will assert a device's
+    info is as expected. An 'ensure' method often does one or more of the
+    above and also may take some other action to enforce the expected state,
+    such as syncing config.
+
+    Example:
+
 
-    available_types = ['sync-failover']
+    '''
+
+    available_types = ['sync-failover', 'sync-only']
     sync_status_entry = 'https://localhost/mgmt/tm/cm/sync-status/0'
 
     def __init__(self, **kwargs):
@@ -78,8 +131,9 @@ def validate(self, **kwargs):
             device_name = get_device_info(device).name
             given_device_names.append(device_name)
         if sorted(queried_device_names) != sorted(given_device_names):
-            msg = ''
+            msg = 'Given devices does not match queried devices.'
             raise UnexpectedDeviceGroupDevices(msg)
+        self.ensure_all_devices_in_sync()
 
     def _check_type(self):
         '''Check that the device group type is correct.
@@ -90,6 +144,10 @@ def _check_type(self):
         if self.type not in self.available_types:
             msg = 'Unsupported cluster type was given: %s' % self.type
             raise DeviceGroupNotSupported(msg)
+        elif self.type == 'sync-only' and self.name != 'device_trust_group':
+            msg = "Management of sync-only device groups only supported for " \
+                "built-in device group named 'device_trust_group'"
+            raise DeviceGroupNotSupported(msg)
 
     def manage_extant(self, **kwargs):
         self.validate(**kwargs)
@@ -121,48 +179,6 @@ def teardown(self):
         pollster(self._check_devices_active_licensed)()
         pollster(self._check_all_devices_in_sync)()
 
-    def scale_up_by_one(self, device):
-        '''Scale device group up by one device
-
-        :param device: ManagementRoot object -- device to add to device group
-        '''
-
-        device_name = get_device_info(device).name
-        if device_name in self._get_device_names_in_group():
-            msg = 'Device: %r is already in device group' % device_name
-            raise DeviceGroupOperationNotSupported(msg)
-        self._check_device_failover_status(device, 'In Sync')
-        self._add_device_to_device_group(device)
-        device.tm.sys.config.exec_cmd('save')
-        self.devices.append(device)
-        self.ensure_all_devices_in_sync()
-
-    def scale_down_by_one(self, device):
-        '''Scale device group down by one device
-
-        :param device: ManagementRoot object -- device to delete from device
-                       group
-        '''
-
-        device_name = get_device_info(device).name
-        if device_name not in self._get_device_names_in_group():
-            msg = 'Device: %r is not in device group' % device_name
-            raise DeviceGroupOperationNotSupported(msg)
-        self._delete_device_from_device_group(device)
-        device.tm.sys.config.exec_cmd('save')
-        name_to_objects = get_device_names_to_objects(self.devices)
-        self.devices.remove(name_to_objects[device_name])
-        self.ensure_all_devices_in_sync()
-
-    def cleanup_scaled_down_device(self, device):
-        '''Remove all devices from device group on orphaned device.
-
-        :param device: bigip object -- device to cleanup
-        '''
-
-        dg = self._delete_all_devices_from_device_group(device)
-        dg.delete()
-
     def _get_device_names_in_group(self):
         '''_get_device_names_in_group
 

f5/multi_device/test/test_device_group.py

@@ -82,6 +82,15 @@ def test_validate_unsupported_type(BigIPs):
     assert 'Unsupported cluster type was given: wrong' == ex.value.message
 
 
+def test_validate_sync_only_not_device_trust_group(BigIPs):
+    with pytest.raises(DeviceGroupNotSupported) as ex:
+        DeviceGroup(
+            devices=BigIPs, device_group_name='test',
+            device_group_type='sync-only', device_group_partition='Common')
+    assert "Management of sync-only device groups only supported for " \
+        "built-in device group named 'device_trust_group'" in ex.value.message
+
+
 def test_validate_type_mismatch(BigIPs):
     with pytest.raises(UnexpectedDeviceGroupType) as ex:
         with mock.patch(
@@ -96,7 +105,7 @@ def test_validate_type_mismatch(BigIPs):
         "device group type: 'sync-failover'" == ex.value.message
 
 
-def test_scale_up_device_already_in_group(DeviceGroupCreateNew, BigIPs):
+def itest_scale_up_device_already_in_group(DeviceGroupCreateNew, BigIPs):
     dg, mock_bigips = DeviceGroupCreateNew
     mock_bigip = mock.MagicMock()
     mock_bigip.tm.cm.devices.get_collection.return_value = \
@@ -111,7 +120,7 @@ def test_scale_up_device_already_in_group(DeviceGroupCreateNew, BigIPs):
     assert "Device: 'test' is already in device group" == ex.value.message
 
 
-def test_scale_down_device_not_in_group(DeviceGroupCreateNew, BigIPs):
+def itest_scale_down_device_not_in_group(DeviceGroupCreateNew, BigIPs):
     dg, mock_bigips = DeviceGroupCreateNew
     mock_bigip = mock.MagicMock()
     mock_bigip.tm.cm.devices.get_collection.return_value = \