manuals/developer-guide/src/main/asciidoc/openflowplugin/odl-ofp-singleton-cluster-aproach.adoc

   1 === Cluster singleton approach in plugin
   2
   3 ==== Basics
   4
   5 ===== Description
   6
   7 The existing OpenDaylight service deployment model assumes symmetric clusters, where all services are activated on all nodes in the cluster. However, many services require that there is a single active service instance per cluster. We call such services 'singleton services'. The Entity Ownership Service (EOS) represents the base Leadership choice for one Entity instance. Every Cluster Singleton service *type* must have its own Entity and every Cluster Singleton service *instance* must have its own Entity Candidate. Every registered Entity Candidate should be notified about its actual role. All this "work" is done by MD-SAL so the Openflowplugin need "only" to register as service in *SingletonClusteringServiceProvider* given by MD-SAL.
   8
   9 ===== Change against using EOS service listener
  10
  11 In this new clustering singleton approach plugin uses API from the MD-SAL project: SingletonClusteringService which comes with three methods.
  12
  13     instantiateServiceInstance()
  14     closeServiceInstance()
  15     getIdentifier()
  16
  17 This service has to be registered to a SingletonClusteringServiceProvider from MD-SAL which take care if mastership is changed in cluster environment.
  18
  19 First method in SingletonClusteringService is being called when the cluster node becomes a MASTER. Second is being called when status changes to SLAVE or device is disconnected from cluster. Last method plugins returns NodeId as ServiceGroupIdentifier
  20 Startup after device is connected
  21
  22 On the start up the plugin we need to initialize first four managers for each working area providing information and services
  23
  24 * Device manager
  25 * RPC manager
  26 * Role manager
  27 * Statistics manager
  28
  29 After connection the device the listener Device manager get the event and start up to creating the context for this connection.
  30 Startup after device connection
  31
  32 Services are managed by SinlgetonClusteringServiceProvider from MD-SAL project. So in startup we simply create a instance of LifecycleService and register all contexts into it.
  33
  34 ==== Role change
  35
  36 Plugin is no longer registered as Entity Ownership Service (EOS) listener therefore does not need to and cannot respond on EOS ownership changes.
  37
  38 ===== Service start
  39
  40 Services start asynchronously but the start is managed by LifecycleService. If something goes wrong LifecycleService stop starting services in context and this speeds up the reconnect process. But the services haven't changed and plugin need to start all this:
  41
  42 *    Activating transaction chain manager
  43 *    Initial gathering of device statistics
  44 *    Initial submit to DS
  45 *    Sending role MASTER to device
  46 *    RPC services registration
  47 *    Statistics gathering start
  48
  49 ===== Service stop
  50
  51 If closeServiceInstance occurred plugin just simply try to store all unsubmitted transactions and close the transaction chain manager, stop RPC services, stop Statistics gathering and after that all unregister txEntity from EOS.