docs/specs/reconciliation-framework.rst

   1 .. contents:: Table of Contents
   2       :depth: 3
   3
   4 ========================
   5 Reconciliation Framework
   6 ========================
   7
   8 `Reconciliation Framework Reviews <https://git.opendaylight.org/gerrit/#/q/topic:bug/8902>`__
   9
  10 This feature aims to overcome the drawbacks of the current reconciliation implementation. As part of this enhancement,
  11 reconciliation framework will be introduced which will coordinate the reconciliation across various applications.
  12
  13 Applications should register themself with reconciliation framework with a specific priority.
  14 Application should decide the priority and the reconciliation framework will use it for executing in an priority.
  15
  16
  17 Problem description
  18 ===================
  19
  20 When a switch connected to controller, the current ODL reconciliation implementation pushes all the
  21 table/meters/groups/flows from the inventory configuration datastore to the switch.
  22
  23 When the switch is connected, all the applications including FRM(Forwarding Rules Manager) will receive the node added
  24 DTCN(Data Tree Change Listener) and starts pushing the flows for the openflow switch. FRM reconciliation will read the
  25 data from the config and starts pushing the flows one by one.
  26 In the meantime, applications can react to the node added DTCN change and will start pushing
  27 the flows through the config DS. With this, there is a high chance the application flow can be overwritten by the old
  28 flows by FRM via reconciliation.
  29
  30 With framework, the problem will be avoided by doing the reconciliation for all the registered services including FRM
  31 and then the openflow switch will be submitted to the DS. With this, applications won't receive the node added DTCN until
  32 registered applications are done with reconciliation for the switch.
  33
  34 The current reconciliation mechanism lacks an ordered execution of tasks  across multiple applications resulting
  35 in the forwarding plane not correctly reflecting the changes in the control plane.
  36 The issue becomes more prominent in case of multi-application scenarios, resulting in errors.
  37
  38 Use Cases
  39 ---------
  40 Priority based/Ordered  Coordination of Reconciliation across multiple applications.
  41
  42 Proposed change
  43 ===============
  44 Reconciliation Framework will be introduced, framework will coordinate the reconciliation across applications.
  45 The Openflow switch won't be advertised to application until Openflow switch is in KNOWN state.
  46
  47 ``KNOWN state`` controller and switch state should be in sync(reconciliation), once the switch connects.
  48
  49 Application participating in reconciliation needs to register with framework.
  50
  51 * Application can either be FRM, FRS or any other application(s).
  52 * Application(s) registering with Reconciliation module is encouraged since: Applications would know the right
  53   Flows/Groups/Meters which needs to be replayed (Add/Delete/Update). FRM/FRS(Forwarding Rules Sync) would not have
  54   application view of flows/group, it would blindly replay the flows/groups. Also flows having idle/hard timeout
  55   can be gracefully handled by application rather than FRM/FRS.
  56
  57 As applications register with reconciliation module
  58
  59 * Reconciliation module maintains the numbers of application registered in an order based on the priority.
  60 * Applications will be executed in the priority order of higher to lower, 1 - Highest n - lowest
  61 * Reconciliation will be triggered as per the priority, applications with same priority will be processed in parallel,
  62   once the higher priority application completed, next priority of applications will be processed.
  63
  64 Openflow switch establishes connections with openflowplugin.
  65
  66 * Openflow switch sends connection request.
  67 * Openflowplugin accepts connection and than establishes the connection.
  68
  69 Openflowplugin after establishing the connection with openflow switch, elects the mastership and invokes reconciliation
  70 framework through ReconciliationFrameworkEvent onDevicePrepared.
  71
  72 * Before invoking the reconciliation API, all the RPCs are registered with MD-SAL by openflowplugin.
  73 * Reconciliation framework will register itself with the MastershipChangeServiceManager.
  74
  75 All registered applications would be indicated to start the reconciliation.
  76 * DeviceInfo would be passed for the API/Event and it contains all the information needed by application.
  77
  78 Application(s) would than fetch the flows / groups for that particular Node, which needs to be replayed.
  79
  80 Application(s) would than replay the selected flows / group on to the switch.
  81
  82 Application(s) would also wait for error from switch, for pre-defined time.
  83
  84 Application(s) would inform the reconciliation status to reconciliation module.
  85
  86 Reconciliation framework would co-relate result status from all the applications and decides the final status.
  87 If success, framework will report back DO_NOTHING and in case of failure it will be DISCONNECT.
  88
  89 Based on result state, openflowplugin should do the following
  90
  91 * On success case, openflowplugin should continue with the openflow switch --> write the switch to the operational datastore.
  92 * On failure case, openflowplugin should disconnect the openflow switch.
  93 * When the switch reconnects, the same steps will be followed again.
  94
  95 When there is a disconnect/mastership change while the reconciliation is going on, openflowplugin should notify the
  96 framework and the framework should halt the current reconciliation.
  97
  98 Implementation Details
  99 ======================
 100 Following new interface will be introduced from Reconciliation framework (RF).
 101
 102 * ReconciliationManager
 103 * ReconciliationNotificationListener
 104
 105 ReconciliationManager
 106 ---------------------
 107 .. code-block:: bash
 108
 109      /* Application who are interested in reconciliation should use this API to register themself to the RF */
 110      /* NotificationRegistration will be return to the registered application, who needs to take of closing the registration */
 111      NotificationRegistration registerService(ReconciliationNotificationListener object);
 112
 113      /* API exposed by RF for get list of registered services */
 114      Map<Integer, List<ReconciliationNotificationListener>> getRegisteredServices();
 115
 116 ReconciliationNotificationListener
 117 ----------------------------------
 118 .. code-block:: bash
 119
 120      /* This method will be a callback from RF to start the application reconciliation */
 121      ListenableFuture<Boolean> startReconciliation(DeviceInfo deviceInfo);
 122
 123      /* This method will be a callback from RF when openflow switch disconnects during reconciliation */
 124      ListenableFuture<Boolean> endReconciliation(DeviceInfo deviceInfo);
 125
 126      /* Priority of the application */
 127      int getPriority();
 128
 129      /* Name of the application */
 130      String getName();
 131
 132      /* Application's intent when the application's reconciliation fails */
 133      ResultState getResultState();
 134
 135 Priority
 136 --------
 137 Framework will maintain the list of registered applications in an order based on the priority. Applications having the
 138 same priority will be executed in parallel and once those are done. Next priority applications will be called.
 139 Consider 2 applications, A and B. A is handling of programming groups and flows and B is handling of programming
 140 flows which is dependent of the groups programmed by A. So, B has to register with lower priority than A.
 141
 142 Application don't do any conflict resolution or guarantee any specific order among the application registered at the
 143 same priority level.
 144
 145 Result State - Intent Action
 146 ----------------------------
 147 When the application fails to reconcile, what is the action that framework should take.
 148
 149 * DO_NOTHING - continue with the next reconciliation
 150 * DISCONNECT - disconnect the switch (reconciliation will start again once the switch connects back)
 151
 152 Name
 153 ----
 154 Name of the application who wants to register for reconciliation
 155
 156 ReconciliationNotificationListener
 157 ----------------------------------
 158 Applications who wants to register should implement ReconciliationNotificationListener interface.
 159
 160 * ReconciliationNotificationListener having api's like startReconciliation and endReconciliation
 161 * startReconciliation --> applications can take action to trigger reconciliation
 162 * endReconciliation --> application can take action to cancel their current reconcile tasks
 163
 164 Command Line Interface (CLI)
 165 ============================
 166 CLI interface will be provided to get all the registered services and their status
 167
 168 * List of registered services
 169 * Status of each application for respective openflow switch
 170
 171 Other Changes
 172 =============
 173
 174 Pipeline changes
 175 ----------------
 176 None.
 177
 178 Yang changes
 179 ------------
 180 None
 181
 182 Configuration impact
 183 --------------------
 184 None
 185
 186 Clustering considerations
 187 -------------------------
 188 None
 189
 190 Other Infra considerations
 191 --------------------------
 192 N.A.
 193
 194 Security considerations
 195 -----------------------
 196 None.
 197
 198 Scale and Performance Impact
 199 ----------------------------
 200 None.
 201
 202 Targeted Release
 203 ----------------
 204 Nitrogen.
 205
 206 Alternatives
 207 ------------
 208 N.A.
 209
 210 Usage
 211 =====
 212
 213 Features to Install
 214 -------------------
 215 Will be updated
 216
 217 REST API
 218 --------
 219 None
 220
 221 CLI
 222 ---
 223 None
 224
 225 Implementation
 226 ==============
 227 Assignee(s)
 228 -----------
 229 Primary assignee:
 230  - Prasanna Huddar <prasanna.k.huddar@ericsson.com>
 231  - Arunprakash D <d.arunprakash@ericsson.com>
 232  - Gobinath Suganthan <gobinath@ericsson.com>
 233
 234 Other contributors:
 235
 236 Work Items
 237 ----------
 238 N.A.
 239
 240 Dependencies
 241 ============
 242 This doesn't add any new dependencies.
 243
 244 Testing
 245 =======
 246 Capture details of testing that will need to be added.
 247
 248 Unit Tests
 249 ----------
 250 None
 251
 252 Integration Tests
 253 -----------------
 254 None
 255
 256 CSIT
 257 ----
 258 None
 259
 260 Documentation Impact
 261 ====================
 262 This feature will not require any change in User Guide.
 263
 264 References
 265 ==========
 266 [1] `Openflowplugin reconciliation enhancements <https://wiki.opendaylight.org/view/OpenDaylight_OpenFlow_Plugin:Reconciliation#Future_Enhancements>`__