docs/specs/group-add-mod.rst

   1 .. contents:: Table of Contents
   2    :depth: 3
   3
   4 ======================================
   5 Group Command OFPGC_ADD_OR_MOD support
   6 ======================================
   7
   8 `Group ADD-MOD Reviews <https://git.opendaylight.org/gerrit/#/q/topic:group-add-mod>`__
   9
  10 This spec addresses following enhancement in Openflowplugin module:
  11
  12 Addition of new command OFPGC_ADD_OR_MOD for OFPT_GROUP_MOD message that adds a new group that
  13 does not exist (like ADD) or modifies an existing groups (like MODIFY).
  14
  15 OFPGC_ADD_OR_MOD group command will be supported only for OVS2.6 and above.
  16
  17 Problem description
  18 ===================
  19 In OpenFlow 1.x the Group Mod commands OFPGC_ADD and OFPGC_MODIFY have strict semantics:
  20 ADD fails if the group exists, while MODIFY fails if the group does not exist. This requires
  21 a controller to exactly know the state of the switch when programming a group in order not run
  22 the risk of getting an OFP Error message in response. This is hard to achieve and maintain at
  23 all times in view of possible switch and controller restarts or other connection losses between
  24 switch and controller.
  25
  26 Due to the un-acknowledged nature of the Group Mod message programming groups safely and
  27 efficiently at the same time is virtually impossible as the controller has to either query
  28 the existence of the group prior to each Group Mod message or to insert a Barrier Request/Reply
  29 after every group to be sure that no Error can be received at a later stage and require a
  30 complicated roll-back of any dependent actions taken between the failed Group Mod and the Error.
  31
  32 Reconciliation
  33 --------------
  34
  35 The current implementation of reconciliation is to read the complete set of groups from config inventory
  36 and start pushing the groups one by one. This will always end up in GROUP_ALREADY_EXITS error as the
  37 reconciliation will always send GROUP ADD.
  38
  39 This can be avoided by reading the groups from switch and compare with the list from inventory config
  40 and push only the delta. This is an overhead comparision and can be simply avoided by updating the
  41 group command as OFPGC_ADD_OR_MOD.
  42
  43 Use Cases
  44 ---------
  45
  46 a. Normal group provisioning via FRM: ADD/UPDATE group should send new command OFPGC_ADD_OR_MOD.
  47
  48 b. Reconciliation of groups should send OFPGC_ADD_OR_MOD. Current implementation of openflowplugin will
  49    always send group add OFPGC_ADD irrespective of the state of the switch. This results in failure with
  50    GROUP_ALREADY_EXISTS error.
  51
  52 Proposed change
  53 ---------------
  54 The implementation of OFPGC_ADD_OR_MOD command is specific to OVS2.6 and above and the same can be extended
  55 to other openflow switch based on the group command support by them.
  56
  57 New configuration parameter will be introduced in default-openflow-connection-config.xml and
  58 legacy-openflow-connection-config.xml, which can be modified by users to enable the GROUP ADD MOD support.
  59
  60 .. code-block:: none
  61    :caption: default(legacy)-openflow-connection-config.xml
  62
  63    <group-add-mod-enabled>false</group-add-mod-enabled>
  64
  65 By default the group-add-mod-enabled flag will be kept as false, which means existing group mod commands
  66 OFPGC_ADD/OFPGC_MODIFY will be used.
  67
  68 GroupMessageSerializer will use the above flag to determine which group command should be set for group add/update.
  69 The above class is applicable for single layer serialization and the for multi-layer serialization changes will be
  70 done in openflowjava GroupModInputMessageFactory java classs.
  71
  72 When flag is enabled, openflowplugin will always send OFPGC_ADD_OR_MOD (32768) for both group add and modify.
  73
  74 Pipeline changes
  75 ----------------
  76 None
  77
  78 Yang changes
  79 ------------
  80
  81 Below yang changes will be done in order to provide configuration support for group-add-mod-enabled field.
  82
  83 .. code-block:: none
  84    :caption: openflow-switch-connection-config.yang
  85
  86    leaf group-add-mod-enabled {
  87         description "Group Add Mod Enabled";
  88         type boolean;
  89         default false;
  90    }
  91
  92 Configuration impact
  93 --------------------
  94 None
  95
  96 Clustering considerations
  97 -------------------------
  98 None
  99
 100 Other Infra considerations
 101 --------------------------
 102 None
 103
 104 Security considerations
 105 -----------------------
 106 None
 107
 108 Scale and Performance Impact
 109 ----------------------------
 110 Unknown
 111
 112 Targeted Release
 113 ----------------
 114 Oxygen
 115
 116 Alternatives
 117 ------------
 118 None
 119
 120 Usage
 121 =====
 122 No external rpc/api will be provided. The implementation is internal to openflowplugin.
 123
 124 User can enable OFPGC_ADD_OR_MOD by changing the value to true in below files,
 125
 126 .. code-block:: none
 127    :caption: default(legacy)-openflow-connection-config.xml
 128
 129    default-openflow-connection-config.xml  <group-add-mod-enabled>false</group-add-mod-enabled>
 130    legacy-openflow-connection-config.xml   <group-add-mod-enabled>false</group-add-mod-enabled>
 131
 132 REST API
 133 --------
 134 No new REST API is being added.
 135
 136 CLI
 137 ---
 138 No new CLI being added.
 139
 140 Implementation
 141 ==============
 142 Assignee(s)
 143 -----------
 144 Primary assignee:
 145   Arunprakash D <d.arunprakash@ericsson.com>
 146
 147 Other contributors:
 148   Gobinath Suganthan <gobinath@ericsson.com>
 149
 150 Work Items
 151 ----------
 152 * Implementation of GROUP ADD MOD support
 153 * Addition of configuration flag to enable/disable group add mod command
 154
 155 Dependencies
 156 ============
 157 No new dependencies.
 158
 159 Testing
 160 =======
 161 Unit Tests
 162 ----------
 163 #. Verify group provisioning via FRM with group-add-mod-supported disabled
 164 #. Verify group provisioning via FRM with group-add-mod-supported enabled
 165 #. Verify reconciliation via FRM with with group-add-mod-supported disabled
 166 #. Verify reconciliation via FRM with with group-add-mod-supported enabled
 167
 168 CSIT
 169 ----
 170 CSIT test cases will be added in future
 171
 172 Documentation Impact
 173 ====================
 174 None
 175
 176 References
 177 ==========
 178 `Openvswitch ADD_OR_MOD <https://github.com/openvswitch/ovs/commit/88b87a36123e5ce3704b5e79950e83651db43ef7>`__