docs/developer-guide/service-function-chaining.rst

   1 Service Function Chaining
   2 =========================
   3
   4 OpenDaylight Service Function Chaining (SFC) Overiew
   5 ----------------------------------------------------
   6
   7 OpenDaylight Service Function Chaining (SFC) provides the ability to
   8 define an ordered list of a network services (e.g. firewalls, load
   9 balancers). These service are then "stitched" together in the network to
  10 create a service chain. This project provides the infrastructure
  11 (chaining logic, APIs) needed for ODL to provision a service chain in
  12 the network and an end-user application for defining such chains.
  13
  14 -  ACE - Access Control Entry
  15
  16 -  ACL - Access Control List
  17
  18 -  SCF - Service Classifier Function
  19
  20 -  SF - Service Function
  21
  22 -  SFC - Service Function Chain
  23
  24 -  SFF - Service Function Forwarder
  25
  26 -  SFG - Service Function Group
  27
  28 -  SFP - Service Function Path
  29
  30 -  RSP - Rendered Service Path
  31
  32 -  NSH - Network Service Header
  33
  34 SFC Classifier Control and Date plane Developer guide
  35 -----------------------------------------------------
  36
  37 Overview
  38 ~~~~~~~~
  39
  40 Description of classifier can be found in:
  41 https://datatracker.ietf.org/doc/draft-ietf-sfc-architecture/
  42
  43 Classifier manages everything from starting the packet listener to
  44 creation (and removal) of appropriate ip(6)tables rules and marking
  45 received packets accordingly. Its functionality is **available only on
  46 Linux** as it leverdges **NetfilterQueue**, which provides access to
  47 packets matched by an **iptables** rule. Classifier requires **root
  48 privileges** to be able to operate.
  49
  50 So far it is capable of processing ACL for MAC addresses, ports, IPv4
  51 and IPv6. Supported protocols are TCP and UDP.
  52
  53 Classifier Architecture
  54 ~~~~~~~~~~~~~~~~~~~~~~~
  55
  56 Python code located in the project repository
  57 sfc-py/common/classifier.py.
  58
  59 .. note::
  60
  61     classifier assumes that Rendered Service Path (RSP) **already
  62     exists** in ODL when an ACL referencing it is obtained
  63
  64 1. sfc\_agent receives an ACL and passes it for processing to the
  65    classifier
  66
  67 2. the RSP (its SFF locator) referenced by ACL is requested from ODL
  68
  69 3. if the RSP exists in the ODL then ACL based iptables rules for it are
  70    applied
  71
  72 After this process is over, every packet successfully matched to an
  73 iptables rule (i.e. successfully classified) will be NSH encapsulated
  74 and forwarded to a related SFF, which knows how to traverse the RSP.
  75
  76 Rules are created using appropriate iptables command. If the Access
  77 Control Entry (ACE) rule is MAC address related both iptables and
  78 ip6tabeles rules re issued. If ACE rule is IPv4 address related, only
  79 iptables rules are issued, same for IPv6.
  80
  81 .. note::
  82
  83     iptables **raw** table contains all created rules
  84
  85 Information regarding already registered RSP(s) are stored in an
  86 internal data-store, which is represented as a dictionary:
  87
  88 ::
  89
  90     {rsp_id: {'name': <rsp_name>,
  91               'chains': {'chain_name': (<ipv>,),
  92                          ...
  93                          },
  94               'sff': {'ip': <ip>,
  95                       'port': <port>,
  96                       'starting-index': <starting-index>,
  97                       'transport-type': <transport-type>
  98                       },
  99               },
 100     ...
 101     }
 102
 103 -  ``name``: name of the RSP
 104
 105 -  ``chains``: dictionary of iptables chains related to the RSP with
 106    information about IP version for which the chain exists
 107
 108 -  ``SFF``: SFF forwarding parameters
 109
 110    -  ``ip``: SFF IP address
 111
 112    -  ``port``: SFF port
 113
 114    -  ``starting-index``: index given to packet at first RSP hop
 115
 116    -  ``transport-type``: encapsulation protocol
 117
 118 Key APIs and Interfaces
 119 ~~~~~~~~~~~~~~~~~~~~~~~
 120
 121 This features exposes API to configure classifier (corresponds to
 122 service-function-classifier.yang)
 123
 124 API Reference Documentation
 125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 126
 127 See: sfc-model/src/main/yang/service-function-classifier.yang
 128
 129 SFC-OVS Plugin
 130 --------------
 131
 132 Overview
 133 ~~~~~~~~
 134
 135 SFC-OVS provides integration of SFC with Open vSwitch (OVS) devices.
 136 Integration is realized through mapping of SFC objects (like SF, SFF,
 137 Classifier, etc.) to OVS objects (like Bridge,
 138 TerminationPoint=Port/Interface). The mapping takes care of automatic
 139 instantiation (setup) of corresponding object whenever its counterpart
 140 is created. For example, when a new SFF is created, the SFC-OVS plugin
 141 will create a new OVS bridge and when a new OVS Bridge is created, the
 142 SFC-OVS plugin will create a new SFF.
 143
 144 SFC-OVS Architecture
 145 ~~~~~~~~~~~~~~~~~~~~
 146
 147 SFC-OVS uses the OVSDB MD-SAL Southbound API for getting/writing
 148 information from/to OVS devices. The core functionality consists of two
 149 types of mapping:
 150
 151 a. mapping from OVS to SFC
 152
 153    -  OVS Bridge is mapped to SFF
 154
 155    -  OVS TerminationPoints are mapped to SFF DataPlane locators
 156
 157 b. mapping from SFC to OVS
 158
 159    -  SFF is mapped to OVS Bridge
 160
 161    -  SFF DataPlane locators are mapped to OVS TerminationPoints
 162
 163 .. figure:: ./images/sfc/sfc-ovs-architecture.png
 164    :alt: SFC < — > OVS mapping flow diagram
 165
 166    SFC < — > OVS mapping flow diagram
 167
 168 Key APIs and Interfaces
 169 ~~~~~~~~~~~~~~~~~~~~~~~
 170
 171 -  SFF to OVS mapping API (methods to convert SFF object to OVS Bridge
 172    and OVS TerminationPoints)
 173
 174 -  OVS to SFF mapping API (methods to convert OVS Bridge and OVS
 175    TerminationPoints to SFF object)
 176
 177 SFC Southbound REST Plugin
 178 --------------------------
 179
 180 Overview
 181 ~~~~~~~~
 182
 183 The Southbound REST Plugin is used to send configuration from DataStore
 184 down to network devices supporting a REST API (i.e. they have a
 185 configured REST URI). It supports POST/PUT/DELETE operations, which are
 186 triggered accordingly by changes in the SFC data stores.
 187
 188 -  Access Control List (ACL)
 189
 190 -  Service Classifier Function (SCF)
 191
 192 -  Service Function (SF)
 193
 194 -  Service Function Group (SFG)
 195
 196 -  Service Function Schedule Type (SFST)
 197
 198 -  Service Function Forwader (SFF)
 199
 200 -  Rendered Service Path (RSP)
 201
 202 Southbound REST Plugin Architecture
 203 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 204
 205 1. **listeners** - used to listen on changes in the SFC data stores
 206
 207 2. **JSON exporters** - used to export JSON-encoded data from
 208    binding-aware data store objects
 209
 210 3. **tasks** - used to collect REST URIs of network devices and to send
 211    JSON-encoded data down to these devices
 212
 213 .. figure:: ./images/sfc/sb-rest-architecture.png
 214    :alt: Southbound REST Plugin Architecture diagram
 215
 216    Southbound REST Plugin Architecture diagram
 217
 218 Key APIs and Interfaces
 219 ~~~~~~~~~~~~~~~~~~~~~~~
 220
 221 The plugin provides Southbound REST API designated to listening REST
 222 devices. It supports POST/PUT/DELETE operations. The operation (with
 223 corresponding JSON-encoded data) is sent to unique REST URL belonging to
 224 certain datatype.
 225
 226 -  Access Control List (ACL):
 227    ``http://<host>:<port>/config/ietf-acl:access-lists/access-list/``
 228
 229 -  Service Function (SF):
 230    ``http://<host>:<port>/config/service-function:service-functions/service-function/``
 231
 232 -  Service Function Group (SFG):
 233    ``http://<host>:<port>/config/service-function:service-function-groups/service-function-group/``
 234
 235 -  Service Function Schedule Type (SFST):
 236    ``http://<host>:<port>/config/service-function-scheduler-type:service-function-scheduler-types/service-function-scheduler-type/``
 237
 238 -  Service Function Forwarder (SFF):
 239    ``http://<host>:<port>/config/service-function-forwarder:service-function-forwarders/service-function-forwarder/``
 240
 241 -  Rendered Service Path (RSP):
 242    ``http://<host>:<port>/operational/rendered-service-path:rendered-service-paths/rendered-service-path/``
 243
 244 Therefore, network devices willing to receive REST messages must listen
 245 on these REST URLs.
 246
 247 .. note::
 248
 249     Service Classifier Function (SCF) URL does not exist, because SCF is
 250     considered as one of the network devices willing to receive REST
 251     messages. However, there is a listener hooked on the SCF data store,
 252     which is triggering POST/PUT/DELETE operations of ACL object,
 253     because ACL is referenced in ``service-function-classifier.yang``
 254
 255 Service Function Load Balancing Developer Guide
 256 -----------------------------------------------
 257
 258 Overview
 259 ~~~~~~~~
 260
 261 SFC Load-Balancing feature implements load balancing of Service
 262 Functions, rather than a one-to-one mapping between Service Function
 263 Forwarder and Service Function.
 264
 265 Load Balancing Architecture
 266 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 267
 268 Service Function Groups (SFG) can replace Service Functions (SF) in the
 269 Rendered Path model. A Service Path can only be defined using SFGs or
 270 SFs, but not a combination of both.
 271
 272 Relevant objects in the YANG model are as follows:
 273
 274 1. Service-Function-Group-Algorithm:
 275
 276    ::
 277
 278        Service-Function-Group-Algorithms {
 279            Service-Function-Group-Algorithm {
 280                String name
 281                String type
 282            }
 283        }
 284
 285    ::
 286
 287        Available types: ALL, SELECT, INDIRECT, FAST_FAILURE
 288
 289 2. Service-Function-Group:
 290
 291    ::
 292
 293        Service-Function-Groups {
 294            Service-Function-Group {
 295                String name
 296                String serviceFunctionGroupAlgorithmName
 297                String type
 298                String groupId
 299                Service-Function-Group-Element {
 300                    String service-function-name
 301                    int index
 302                }
 303            }
 304        }
 305
 306 3. ServiceFunctionHop: holds a reference to a name of SFG (or SF)
 307
 308 Key APIs and Interfaces
 309 ~~~~~~~~~~~~~~~~~~~~~~~
 310
 311 This feature enhances the existing SFC API.
 312
 313 REST API commands include: \* For Service Function Group (SFG): read
 314 existing SFG, write new SFG, delete existing SFG, add Service Function
 315 (SF) to SFG, and delete SF from SFG \* For Service Function Group
 316 Algorithm (SFG-Alg): read, write, delete
 317
 318 Bundle providing the REST API: sfc-sb-rest \* Service Function Groups
 319 and Algorithms are defined in: sfc-sfg and sfc-sfg-alg \* Relevant JAVA
 320 API: SfcProviderServiceFunctionGroupAPI,
 321 SfcProviderServiceFunctionGroupAlgAPI
 322
 323 Service Function Scheduling Algorithms
 324 --------------------------------------
 325
 326 Overview
 327 ~~~~~~~~
 328
 329 When creating the Rendered Service Path (RSP), the earlier release of
 330 SFC chose the first available service function from a list of service
 331 function names. Now a new API is introduced to allow developers to
 332 develop their own schedule algorithms when creating the RSP. There are
 333 four scheduling algorithms (Random, Round Robin, Load Balance and
 334 Shortest Path) are provided as examples for the API definition. This
 335 guide gives a simple introduction of how to develop service function
 336 scheduling algorithms based on the current extensible framework.
 337
 338 Architecture
 339 ~~~~~~~~~~~~
 340
 341 The following figure illustrates the service function selection
 342 framework and algorithms.
 343
 344 .. figure:: ./images/sfc-sf-selection-arch.png
 345    :alt: SF Scheduling Algorithm framework Architecture
 346
 347    SF Scheduling Algorithm framework Architecture
 348
 349 The YANG Model defines the Service Function Scheduling Algorithm type
 350 identities and how they are stored in the MD-SAL data store for the
 351 scheduling algorithms.
 352
 353 The MD-SAL data store stores all informations for the scheduling
 354 algorithms, including their types, names, and status.
 355
 356 The API provides some basic APIs to manage the informations stored in
 357 the MD-SAL data store, like putting new items into it, getting all
 358 scheduling algorithms, etc.
 359
 360 The RESTCONF API provides APIs to manage the informations stored in the
 361 MD-SAL data store through RESTful calls.
 362
 363 The Service Function Chain Renderer gets the enabled scheduling
 364 algorithm type, and schedules the service functions with scheduling
 365 algorithm implementation.
 366
 367 Key APIs and Interfaces
 368 ~~~~~~~~~~~~~~~~~~~~~~~
 369
 370 While developing a new Service Function Scheduling Algorithm, a new
 371 class should be added and it should extend the base schedule class
 372 SfcServiceFunctionSchedulerAPI. And the new class should implement the
 373 abstract function:
 374
 375 ``public List<String> scheduleServiceFuntions(ServiceFunctionChain chain, int serviceIndex)``.
 376
 377 -  **``ServiceFunctionChain chain``**: the chain which will be rendered
 378
 379 -  **``int serviceIndex``**: the initial service index for this rendered
 380    service path
 381
 382 -  **``List<String>``**: a list of service funtion names which scheduled
 383    by the Service Function Scheduling Algorithm.
 384
 385 API Reference Documentation
 386 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 387
 388 Please refer the API docs generated in the mdsal-apidocs.
 389