docs/specs/oxygen/qos.rst

   1 .. contents:: Table of Contents
   2       :depth: 3
   3
   4 =======================================================
   5 Neutron Quality of Service API Enhancements for NetVirt
   6 =======================================================
   7
   8 QoS patches: https://git.opendaylight.org/gerrit/#/q/topic:qos
   9
  10 The Carbon release will enhance the initial implementation of Neutron
  11 QoS API [#]_ support for NetVirt which was released in Boron.  The
  12 Boron released added support for Neutron QoS policies and the
  13 Egress bandwidth rate limiting rule.  The Carbon release will update the
  14 QoS feature set of NetVirt by providing support for the DSCP Marking
  15 rule and QoS Rule capability reporting.
  16
  17 Problem description
  18 ===================
  19
  20 It is important to be able to configure QoS attributes of workloads on
  21 virtual networks.  The Neutron QoS API provides a method for defining
  22 QoS policies and associated rules which can be applied to Neutron Ports
  23 and Networks.  These rules include:
  24
  25 - Egress Bandwidth Rate Limiting
  26 - DSCP Marking
  27
  28 (Note that for the Neutron API, the direction of traffic flow (ingress, egress)
  29 is from the perspective of the OpenStack instance.)
  30
  31 As a Neutron provider for ODL, NetVirt will provide the ability to report
  32 back to Neutron its QoS rule capabilties and provide the ability to
  33 configure and manage the supported QoS rules on supported backends
  34 (e.g. OVS, ...).  The key changes in the Carbon release will be the
  35 addition of support for the DSCP Marking rule.
  36
  37 Use Cases
  38 ---------
  39
  40 Neutron QoS API support, including:
  41
  42 - Egress rate limiting -
  43   Drop traffic that exceeeds the specified rate parameters for a
  44   Neutron Port or Network.
  45
  46 - DSCP Marking -
  47   Set the DSCP field for IP packets arriving from Neutron Ports
  48   or Networks.
  49
  50 - Reporting of QoS capabilities -
  51   Report to Neutron which QoS Rules are supported.
  52
  53 Proposed change
  54 ===============
  55
  56 To handle DSCP marking, listener support will be added to the
  57 *neutronvpn* service to respond to changes in DSCP Marking
  58 Rules in QoS Policies in the Neutron Northbound QoS models [#]_ [#]_ .
  59
  60 To implement DSCP marking support, a new ingress (from vswitch
  61 perspective) QoS Service is defined in Genius.  When DSCP Marking rule
  62 changes are detected, a rule in a new OpenFlow table for
  63 QoS DSCP marking rules will be updated.
  64
  65 The QoS service will be bound to an interface when a DSCP Marking
  66 rule is added and removed when the DSCP Marking rule is deleted.
  67 The QoS service follows the DHCP service and precedes the IPV6
  68 service in the sequence of Genius ingress services.
  69
  70 Some use cases for DSCP marking require that the DSCP mark set on the inner packet
  71 be replicated to the DSCP marking in the outer packet.  Therefore, for packets egressing out
  72 of OVS through vxlan/gre tunnels the option to copy the DSCP bits from the inner IP header
  73 to the outer IP header is needed.
  74 Marking of the inner header is done via OpenFlow rules configured on the corresponding Neutron port
  75 as described above. For cases where the outer tunnel header should have a copy of the inner
  76 header DSCP marking, the ``tos`` option on the tunnel interface in OVSDB must be configured
  77 to the value ``inherit``.
  78 The setting of the ``tos`` option is done with a configurable parameter defined in the ITM module.
  79 By default the ``tos`` option is set to *0* as specified in the OVSDB specification [#]_ .
  80
  81 On the creation of new tunnels, the ``tos`` field will be set to either the user provided value
  82 or to the default value, which may be controlled via configuration.  This will result in
  83 the tunnel-options field in the IFM (Interface Manager) to be set which will in turn cause
  84 the ``options`` field for the tunnel interface on the OVSDB node to be configured.
  85
  86 To implement QoS rule capability reporting back towards Neutron, code will
  87 be added to the *neutronvpn* service to populate the operational qos-rule-types
  88 list in the Neutron Northbound Qos model [3]_ with a list of the supported
  89 QoS rules - which will be the bandwidth limit rule and DSCP marking rule for
  90 the Carbon release.
  91
  92 Pipeline changes
  93 ----------------
  94 A new QoS DSCP table is added to support the new QoS Service:
  95
  96 =============   =====================================  ===========================
  97 Table           Match                                  Action
  98 =============   =====================================  ===========================
  99 QoS DSCP [90]   Ethtype == IPv4 or IPv6 AND LPort tag  Mark packet with DSCP value
 100 =============   =====================================  ===========================
 101
 102 Yang changes
 103 ------------
 104 A new leaf ``option-tunnel-tos`` is added to ``tunnel-end-points`` in *itm-state.yang* and to
 105 ``vteps`` in *itm.yang*.
 106
 107
 108 .. code-block:: none
 109    :caption: itm-state.yang
 110    :emphasize-lines: 39-46
 111
 112    list tunnel-end-points {
 113        ordered-by user;
 114        key "portname VLAN-ID ip-address tunnel-type";
 115
 116        leaf portname {
 117            type string;
 118        }
 119        leaf VLAN-ID {
 120            type uint16;
 121        }
 122        leaf ip-address {
 123            type inet:ip-address;
 124        }
 125        leaf subnet-mask {
 126            type inet:ip-prefix;
 127        }
 128        leaf gw-ip-address {
 129            type inet:ip-address;
 130        }
 131        list tz-membership {
 132            key "zone-name";
 133            leaf zone-name {
 134                type string;
 135            }
 136        }
 137        leaf interface-name {
 138            type string;
 139        }
 140        leaf tunnel-type {
 141            type identityref {
 142                base odlif:tunnel-type-base;
 143            }
 144        }
 145        leaf option-of-tunnel {
 146            description "Use flow based tunnels for remote-ip";
 147            type boolean;
 148            default false;
 149        }
 150        leaf option-tunnel-tos {
 151            description "Value of ToS bits to be set on the encapsulating
 152                packet.  The value of 'inherit' will copy the DSCP value
 153                from inner IPv4 or IPv6 packets.  When ToS is given as
 154                and numberic value, the least significant two bits will
 155                be ignored. ";
 156            type string;
 157        }
 158    }
 159
 160
 161 .. code-block:: none
 162    :caption: itm.yang
 163    :emphasize-lines: 17-24
 164
 165    list vteps {
 166        key "dpn-id portname";
 167        leaf dpn-id {
 168            type uint64;
 169        }
 170        leaf portname {
 171            type string;
 172        }
 173        leaf ip-address {
 174            type inet:ip-address;
 175        }
 176        leaf option-of-tunnel {
 177            description "Use flow based tunnels for remote-ip";
 178            type boolean;
 179            default false;
 180        }
 181        leaf option-tunnel-tos {
 182            description "Value of ToS bits to be set on the encapsulating
 183                packet.  The value of 'inherit' will copy the DSCP value
 184                from inner IPv4 or IPv6 packets.  When ToS is given as
 185                and numberic value, the least significant two bits will
 186                be ignored. ";
 187            type string;
 188        }
 189    }
 190
 191
 192 A configurable parameter ``default-tunnel-tos`` is added to *itm-config.yang* which
 193 defines the default ToS value to be applied to tunnel ports.
 194
 195 .. code-block:: none
 196    :caption: itm-config.yang
 197    :emphasize-lines: 1-13
 198
 199    container itm-config {
 200        config true;
 201
 202        leaf default-tunnel-tos {
 203            description "Default value of ToS bits to be set on the encapsulating
 204                packet.  The value of 'inherit' will copy the DSCP value
 205                from inner IPv4 or IPv6 packets.  When ToS is given as
 206                and numberic value, the least significant two bits will
 207                be ignored. ";
 208            type string;
 209            default 0;
 210        }
 211    }
 212
 213 Configuration impact
 214 ---------------------
 215 A configurable parameter ``default-tunnel-tos`` is added to
 216 *genius-itm-config.xml* which specifies the default ToS to
 217 use on a tunnel if it is not specified by the user when a
 218 tunnel is created.  This value may be set to ``inherit`` for
 219 some DSCP Marking use cases.
 220
 221 .. code-block:: none
 222    :caption: genius-itm-config.xml
 223
 224    <itm-config xmlns="urn:opendaylight:genius:itm:config">
 225        <default-tunnel-tos>0</default-tunnel-tos>
 226    </itm-config>
 227
 228
 229
 230 Clustering considerations
 231 -------------------------
 232 None.
 233
 234 Other Infra considerations
 235 --------------------------
 236 None.
 237
 238 Security considerations
 239 -----------------------
 240 None.
 241
 242 Scale and Performance Impact
 243 ----------------------------
 244 Additional OpenFlow packets will be generated to configure DSCP marking rules in response
 245 to QoS Policy changes coming from Neutron.
 246
 247 Targeted Release
 248 -----------------
 249 Carbon
 250
 251 Alternatives
 252 ------------
 253 Use of OpenFlow meters was desired, but the OpenvSwitch datapath implementation
 254 does not support meters (although the OpenvSwitch OpenFlow protocol implementation
 255 does support meters).
 256
 257 Usage
 258 =====
 259 The user will use the QoS support by enabling and configuring the
 260 QoS extension driver for networking-odl.  This will allow QoS Policies and
 261 Rules to be configured for Neuetron Ports and Networks using Neutron.
 262
 263 Perform the following configuration steps:
 264
 265 -  In *neutron.conf* enable the QoS service by appending ``qos`` to
 266    the ``service_plugins`` configuration:
 267
 268    .. code-block:: none
 269       :caption: /etc/neutron/neutron.conf
 270
 271       service_plugins = odl-router, qos
 272
 273 -  Add the QoS notification driver to the *neutron.conf* file as follows:
 274
 275    .. code-block:: none
 276       :caption: /etc/neutron/neutron.conf
 277
 278       [qos]
 279       notification_drivers = odl-qos
 280
 281 -  Enable the QoS extension driver for the core ML2 plugin.
 282    In file *ml2.conf.ini* append ``qos`` to ``extension_drivers``
 283
 284    .. code-block:: none
 285       :caption: /etc/neutron/plugins/ml2/ml2.conf.ini
 286
 287       [ml2]
 288       extensions_drivers = port_security,qos
 289
 290 Features to Install
 291 -------------------
 292 Install the ODL Karaf feature for NetVirt (no change):
 293
 294 - odl-netvirt-openstack
 295
 296 REST API
 297 --------
 298 None.
 299
 300 CLI
 301 ---
 302 Refer to the Neutron CLI Reference [#]_ for the Neutron CLI command syntax
 303 for managing QoS policies and rules for Neutron networks and ports.
 304
 305 Implementation
 306 ==============
 307
 308 Assignee(s)
 309 -----------
 310 Who is implementing this feature? In case of multiple authors, designate a
 311 primary assigne and other contributors.
 312
 313 Primary assignee:
 314
 315 -  Poovizhi Pugazh <poovizhi.p@ericsson.com>
 316
 317 Other contributors:
 318
 319 -  Ravindra Nath Thakur <ravindra.nath.thakur@ericsson.com>
 320 -  Eric Multanen <eric.w.multanen@intel.com>
 321 -  Praveen Mala <praveen.mala@intel.com> (including CSIT)
 322
 323
 324 Work Items
 325 ----------
 326 Task list in Carbon Trello: https://trello.com/c/bLE2n2B1/14-qos
 327
 328 Dependencies
 329 ============
 330 Genius project - Code [#]_ to support QoS Service needs to be added.
 331
 332 Neutron Northbound - provides the Neutron QoS models for policies and rules (already done).
 333
 334
 335 Following projects currently depend on NetVirt:
 336  Unimgr
 337
 338 Testing
 339 =======
 340 Capture details of testing that will need to be added.
 341
 342 Unit Tests
 343 ----------
 344
 345 Integration Tests
 346 -----------------
 347
 348 CSIT
 349 ----
 350
 351 Documentation Impact
 352 ====================
 353 Documentation to describe use of Neutron QoS support with NetVirt
 354 will be added.
 355
 356 OpenFlow pipeline documentation updated to show QoS service table.
 357
 358 References
 359 ==========
 360
 361 http://specs.openstack.org/openstack/neutron-specs/specs/newton/ml2-qos-with-dscp.html
 362
 363 ODL gerrit adding QoS models to Neutron Northbound: https://git.opendaylight.org/gerrit/#/c/37165/
 364
 365 .. [#] Neutron QoS http://docs.openstack.org/developer/neutron/devref/quality_of_service.html
 366 .. [#] Neutron Northbound QoS Model Extensions https://github.com/opendaylight/neutron/blob/master/model/src/main/yang/neutron-qos-ext.yang
 367 .. [#] Neutron Northbound QoS Model https://github.com/opendaylight/neutron/blob/master/model/src/main/yang/neutron-qos.yang
 368 .. [#] OVSDB Schema http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf
 369 .. [#] Neutron CLI Reference http://docs.openstack.org/cli-reference/neutron.html#neutron-qos-available-rule-types
 370 .. [#] Genius code supporting QoS service https://git.opendaylight.org/gerrit/#/c/49084/