docs/specs/reconciliation-cli.rst

   1 .. contents:: Table of Contents
   2       :depth: 3
   3
   4 ============================
   5 Reconciliation CLI and Alarm
   6 ============================
   7
   8 This spec addresses following enhancement in Openflowplugin module:
   9
  10 Addition of user triggered reconciliation via karaf cli command or rpc in Openflowplugin.
  11
  12 Problem description
  13 ===================
  14 Whenever there is a state (flow/group) mismatch between config inventory and Openflow switch, user has to either restart
  15 the Openflow switch or odl controller. This will sync the state again between odl controller and Openflow switch.
  16
  17 Reconciliation
  18 ==============
  19 User can trigger reconciliation to sync the state between controller and Openflow switch. It can be done either via
  20 karaf cli command or rest rpc.
  21
  22 Reconciliation Alarm
  23 ====================
  24 Reconciliation alarm will be generated whenever user trigger the reconciliation via cli command or rest rpc and the
  25 same will be cleared once reconciliation is completed.
  26
  27 Use Cases
  28 ---------
  29
  30 a. Trigger reconciliation for a single Openflow switch
  31 b. Trigger reconciliation for a list of Openflow switch
  32 c. Trigger reconciliation for all the connected Openflow switches
  33 d. Raise alarm whenever user triggers reconciliation for a Openflow switch
  34 e. Clear the alarm when the reconciliation completed for a Openflow swtich
  35
  36 Proposed change
  37 ---------------
  38 Karaf CLI command will be added to trigger reconciliation for the given Openflow nodes.
  39 Rest rpc will be exposed to trigger reconciliation for the given Openflow nodes.
  40
  41 Feature `odl-openflowplugin-app-southbound-cli` should be installed in order to get these karaf cli and rest rpc.
  42 This feature is not part of any existing openflowplugin features and has to be installed explicitly by user.
  43
  44 Ref: `Southbound CLI <https://docs.opendaylight.org/projects/openflowplugin/en/latest/specs/southbound-cli.html>`__
  45
  46 Below two CLIs will be added,
  47
  48 * openflow:reconcile
  49 * openflow:getreconciliationcount
  50
  51 Pipeline changes
  52 ----------------
  53 None
  54
  55 Yang changes
  56 ------------
  57
  58 .. code-block:: none
  59    :caption: reconciliation.yang
  60
  61    container reconciliation-counter {
  62        description "Number of reconciliation triggered for openflow nodes";
  63        config false;
  64        list reconcile-counter {
  65            key node-id;
  66            uses counter;
  67        }
  68    }
  69
  70    grouping counter {
  71        leaf node-id {
  72            type uint64;
  73        }
  74        leaf success-count {
  75            type uint32;
  76            default 0;
  77        }
  78        leaf failure-count {
  79            type uint32;
  80            default 0;
  81        }
  82        leaf last-request-time {
  83            description "Timestamp when reconciliation was last requested";
  84            type string;
  85        }
  86    }
  87
  88    container reconciliation-state {
  89        description "Reconciliation state for the given openflow nodes";
  90        config false;
  91        list reconciliation-state-list {
  92            key node-id;
  93            uses node-reconcile-state;
  94        }
  95    }
  96
  97    grouping node-reconcile-state {
  98        leaf node-id {
  99            type uint64;
 100        }
 101        leaf state {
 102            description "Expresses the current state of the reconcile on a specific NODE";
 103            type enumeration {
 104                enum IN_PROGRESS;
 105                enum COMPLETED;
 106                enum FAILED;
 107            }
 108        }
 109    }
 110
 111    rpc reconcile {
 112        description "Request the reconciliation for given device or set of devices to the controller."
 113        input {
 114            leaf-list nodes {
 115                description "List of nodes to be reconciled";
 116                type uint64;
 117            }
 118            leaf reconcile-all-nodes {
 119                description "Flag to indicate that all nodes to be reconciled";
 120                type boolean;
 121                mandatory false;
 122                default false;
 123            }
 124        }
 125        output {
 126            leaf result {
 127                type boolean;
 128            }
 129            leaf-list inprogress-nodes {
 130                description "List of nodes that are already in reconciling mode";
 131                type uint64;
 132            }
 133        }
 134    }
 135
 136 Targeted Release
 137 ----------------
 138 Flourine
 139
 140 Alternatives
 141 ------------
 142 Disconnect the device from controller and reconnect or restart the controller.
 143
 144 REST API
 145 --------
 146
 147 * POST: http://localhost:8181/restconf/operations/reconciliation:reconcile
 148 * GET: http://localhost:8181/restconf/operational/reconciliation:reconciliation-counter
 149
 150 Usage
 151 =====
 152 Install ``odl-openflowplugin-app-southbound-cli`` feature.
 153
 154 CLI:
 155 ----
 156 Trigger reconciliation for a connected openflow node via cli command ``openflow:reconcile``.
 157
 158 .. code-block:: bash
 159    :caption: openflow:reconcile
 160
 161    opendaylight-user@root>openflow:reconcile 244711506862915
 162    reconcile successfully completed for the nodes
 163
 164 Trigger reconciliation for all the connected openflow nodes via cli command ``openflow:reconcile -all``.
 165
 166 .. code-block:: bash
 167    :caption: openflow:reconcile -all
 168
 169          opendaylight-user@root>openflow:reconcile -all
 170          reconcile successfully completed for the nodes
 171
 172 Get details about number of times user triggered reconciliation for openflow nodes via ``openflow:getreconciliationcount``.
 173
 174 .. code-block:: bash
 175    :caption: openflow:getreconciliationcount
 176
 177    opendaylight-user@root>openflow:getreconcilecount
 178    NodeId              ReconcileSuccessCount     ReconcileFailureCount     LastReconcileTime
 179    ------------------------------------------------------------------------------------------------
 180    244711506862915     2                         0                         2018-06-06T11:51:51.989
 181
 182 REST:
 183 -----
 184 Trigger reconciliation for a single datapath node.
 185
 186 .. code-block:: bash
 187    :caption: http://localhost:8181/restconf/operations/reconciliation:reconcile
 188
 189    POST /restconf/operations/reconciliation:reconcile
 190    {
 191      "input" :  {
 192        "nodes":["244711506862915"]
 193      }
 194    }
 195
 196
 197 Get reconciliation counter details
 198
 199 .. code-block:: bash
 200    :caption: http://localhost:8181/restconf/operational/reconciliation:reconciliation-counter
 201
 202    GET /restconf/operational/reconciliation:reconciliation-counter
 203
 204    OUTPUT:
 205    =======
 206    Request URL
 207    http://localhost:8181/restconf/operational/reconciliation:reconciliation-counter
 208
 209    Response Body
 210    {
 211      "reconciliation-counter": {
 212        "reconcile-counter": [
 213          {
 214            "node-id": 244711506862915,
 215            "success-count": 4,
 216            "last-request-time": "2018-06-06T12:09:53.325"
 217          }
 218        ]
 219      }
 220    }
 221
 222
 223 Trigger reconciliation for a openflow switch using routed rpc. This rpc will be exposed without installing southbound-cli
 224 feature and user can trigger reconciliation for the given Openflow node. This will not affect the counter and alarm.
 225
 226 .. code-block:: bash
 227    :caption: http://localhost:8181/restconf/operations/reconciliation:reconcile-node
 228
 229    POST /restconf/operations/reconciliation:reconcile-node
 230    {
 231      "input": {
 232        "nodeId": "244711506862915",
 233        "node": "/opendaylight-inventory:nodes/opendaylight-inventory:node[opendaylight-inventory:id='openflow:244711506862915']"
 234      }
 235    }
 236
 237    Request URL
 238    http://localhost:8181/restconf/operations/reconciliation:reconcile-node
 239
 240    Response Body
 241    {
 242      "output": {
 243        "result": true
 244      }
 245    }
 246
 247 Implementation
 248 ==============
 249 Assignee(s)
 250 -----------
 251 Primary assignee:
 252
 253 * Arunprakash D <d.arunprakash@ericsson.com>
 254
 255 Contributors:
 256
 257 * Suja T <suja.t@ericsson.com>
 258 * Somashekhar Javalagi <somashekhar.manohara.javalagi@ericsson.com>
 259
 260 Work Items
 261 ----------
 262 * Implementation of cli to trigger reconciliation for openflow node(s).
 263 * Implementation of reconciliation alarm for user triggered reconciliation.
 264
 265 Dependencies
 266 ============
 267 No new dependencies.
 268
 269 Testing
 270 =======
 271 Unit Tests
 272 ----------
 273 #. Verify reconciliation for single openflow node
 274 #. Verify reconciliation for list of openflow nodes
 275 #. Verify reconciliation for all the openflow nodes
 276 #. Verify reconciliation alarm generated for user triggered reconciliation node
 277 #. Verify reconciliation alarm cleared once the reconciliation completed
 278
 279 CSIT
 280 ----
 281 None
 282
 283 Documentation Impact
 284 ====================
 285 None
 286
 287 References
 288 ==========
 289 None