docs/user-guide/fabric-as-a-service.rst

   1 Fabric As A Service
   2 ===================
   3
   4 This document describes, from a user’s or application’s perspective, how
   5 to use the Fabric As A Service (FaaS) feature in OpenDaylight. This
   6 document contains configuration, administration, and management sections
   7 for the FaaS feature.
   8
   9 Overview
  10 --------
  11
  12 Currently network applications and network administrators mostly rely on
  13 lower level interfaces such as CLI, SNMP, OVSDB, NETCONF or OpenFlow to
  14 directly configure individual device for network service provisioning.
  15 In general, those interfaces are:
  16
  17 -  Technology oriented, not application oriented.
  18
  19 -  Vendor specific
  20
  21 -  Individual device oriented, not network oriented.
  22
  23 -  Not declarative, complicated and procedure oriented.
  24
  25 To address the gap between application needs and network interface,
  26 there are a few application centric language proposed in OpenDaylight
  27 including Group Based Policy (GBP), Network Intent Composition (NIC),
  28 and NEtwork MOdeling (NEMO) trying to replace traditional southbound
  29 interface to application. Those languages are top-down abstractions and
  30 model application requirements in a more application-oriented way.
  31
  32 After being involved with GBP development for a while, we feel the top
  33 down model still has a quite gap between the model and the underneath
  34 network since the existing interfaces to network devices lack of
  35 abstraction makes it very hard to map high level abstractions to the
  36 physical network. Often the applications built with these low level
  37 interfaces are coupled tightly with underneath technology and make the
  38 application’s architecture monolithic, error prone and hard to maintain.
  39
  40 We think a bottom-up abstraction of network can simplify, reduce the
  41 gap, and make it easy to implement the application centric model.
  42 Moreover in some uses cases, an interface with network service oriented
  43 are still desired for example from network monitoring/troubleshooting
  44 perspective. That’s where the Fabric as a Service comes in.
  45
  46 FaaS Architecture
  47 -----------------
  48
  49 Fabric and its controller (Fabric Controller)
  50     The Fabric object provides an abstraction of a homogeneous network
  51     or portion of the network and also has a built in Fabric controller
  52     which provides management plane and control plane for the fabric.
  53     The fabric controller implements the services required in Fabric
  54     Service and monitor and control the fabric operation.
  55
  56 Fabric Manager
  57     Fabric Manager manages all the fabric objects. also Fabric manager
  58     acts as a Unified Fabric Controller which provides inter-connect
  59     fabric control and configuration Also Fabric Manager is FaaS API
  60     service via Which FaaS user level logical network API (the top level
  61     API as mentioned previously) exposed and implemented.
  62
  63 FaaS render for GBP (Group Based Policy)
  64     FaaS render for GBP is an application of FaaS and provides the
  65     rendering service between GBP model and logical network model
  66     provided by Fabric Manager.
  67
  68 FaaS RESTCONF API
  69 -----------------
  70
  71 FaaS Provides two layers API:
  72
  73 -  The top layer is a **user level logical network** API which defines
  74    CRUD services operating on the following abstracted constructs:
  75
  76    -  vcontainer - virtual container
  77
  78    -  logical Port - a input/out/access point of a logical device
  79
  80    -  logical link - connects ports
  81
  82    -  logical switch - a layer 2 forwarding device
  83
  84    -  logical router - a layer 3 forwarding device
  85
  86    -  Subnet
  87
  88    -  Rule/ACL
  89
  90    -  End Points Registration
  91
  92    -  End Points Attachment
  93
  94 Through these constructs, a logical network can be described without
  95 users knowing too much details about the physical network device and
  96 technology, i.e. users' network services is decoupled from underneath
  97 physical infrastructure. This decoupling brought the benefit that the
  98 users defined service is not locked in with any specific technology or
  99 physical devices. FaaS maps the logical network to the physical network
 100 configuration automatically which in maximum eliminates the manual
 101 provisioning work. As a result, human error is avoided and OPEX for
 102 network operators is massively reduced. Moreover migration from one
 103 technology to another is much easier to do and transparent to users'
 104 services.
 105
 106 -  The second layer defines an abstraction layer called **Fabric** API.
 107    The idea is to abstract network into a topology formed by a
 108    collections of fabric objects other than varies of physical
 109    devices.Each Fabric object provides a collection of unified services.
 110    The top level API enables application developers or users to write
 111    applications to map high level model such as GBP, Intent etc… into a
 112    logical network model, while the lower level gives the application
 113    more control to individual fabric object level. More importantly the
 114    Fabric API is more like SPI (Service Provider API) a fabric provider
 115    or vendor can implement the SPI based on its own Fabric technique
 116    such as TRILL, SPB etc …
 117
 118 This document is focused on the top layer API. For how to use second
 119 level API operation, please refer to FaaS developer guide for more
 120 details.
 121
 122 .. note::
 123
 124     that for any JSON data or link not described here, please go to
 125     `http://${ipaddress}:8181/apidoc/explorer/index.htm <http://${ipaddress}:8181/apidoc/explorer/index.htm>`__
 126     for details or clarification.
 127
 128 Resource Management API
 129 -----------------------
 130
 131 The FaaS Resource Management API provides services to allocate and
 132 reclaim the network resources provided by Fabric object. Those APIs can
 133 be accessed via RESTCONF rendered from YANG in MD-SAL.
 134
 135 -  Name: Create virtual container
 136
 137    -  virtual container is an collections of resources allocated to a
 138       tenant, for example, a list of physical ports, bandwidth or L2
 139       network or logical routers quantity. etc…
 140
 141    -  `http://${ipaddress}:8181/restconf/operations/vcontainer-topology:create-vcontainer <http://${ipaddress}:8181/restconf/operations/vcontainer-topology:create-vcontainer>`__
 142
 143    -  Description: create a given virtual container.
 144
 145 -  Name: assign or remove fabric resource to a virtual container
 146
 147    -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-vfabric-to-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-vfabric-to-ld-node>`__
 148
 149    -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:rm-vfabric-to-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:rm-vfabric-to-ld-node>`__
 150
 151 -  Name: assign or remove appliance to a virtual container
 152
 153    -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-appliance-to-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-appliance-to-ld-node>`__
 154
 155    -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:rm-appliance-to-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:rm-appliance-to-ld-node>`__
 156
 157 -  Name: create or remove a child container
 158
 159    -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:create-child-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:create-child-ld-node>`__
 160
 161    -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:rm-child-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:rm-child-ld-node>`__
 162
 163 -  RESTCONF path for Virtual Container Datastore query (note:
 164    vcontainer-id equals tenantID for now):
 165
 166    -  `http://${ipaddress}:8181/restconf/config/network-topology/topology/{vcontainer-id}/vc-topology-attributes/ <http://${ipaddress}:8181/restconf/config/network-topology/topology/{vcontainer-id}/vc-topology-attributes/>`__
 167
 168    -  `http://${ipaddress}:8181/restconf/config/network-topology/topology/{vcontainer-id}/node/{net-node-id}/vc-net-node-attributes <http://${ipaddress}:8181/restconf/config/network-topology/topology/{vcontainer-id}/node/{net-node-id}/vc-net-node-attributes>`__
 169
 170    -  `http://${ipaddress}:8181/restconf/config/network-topology/topology/{vcontainer-id}/node/{ld-node-id}/vc-ld-node-attributes <http://${ipaddress}:8181/restconf/config/network-topology/topology/{vcontainer-id}/node/{ld-node-id}/vc-ld-node-attributes>`__
 171
 172 Installing Fabric As A Service
 173 ------------------------------
 174
 175 To install FaaS, download OpenDaylight and use the Karaf console to
 176 install the following feature: **odl-restconf** **odl-faas-all**
 177 **odl-groupbasedpolicy-faas** (if needs to use FaaS to render GBP)
 178
 179 Configuring FaaS
 180 ----------------
 181
 182 This section gives details about the configuration settings for various
 183 components in FaaS.
 184
 185 The FaaS configuration files for the Karaf distribution are located in
 186 distribution/karaf/target/assembly/etc/faas
 187
 188 -  akka.conf
 189
 190    -  This file contains configuration related to clustering. Potential
 191       configuration properties can be found on the akka website at
 192       http://doc.akka.io
 193
 194 -  fabric-factory.xml
 195
 196 -  vxlan-fabric.xml
 197
 198 -  vxlan-fabric-ovs-adapter.xml
 199
 200    -  Those 3 files are used to initialize fabric module and located
 201       under distribution/karaf/target/assembly/etc/opendaylight/karaf
 202
 203 Managing FaaS
 204 -------------
 205
 206 Start opendaylight karaf distribution
 207
 208 -  *>bin/karaf* Then From karaf console,Install features in the
 209    following order:
 210
 211 -  *>feature:Install odl-restconf*
 212
 213 -  *>feature:install odl-faas-all*
 214
 215 -  *>feature install odl-groupbasedpolicy-faas*
 216
 217 After installing features above, users can manage Fabric resource and
 218 FaaS logical network channels from the APIDOCS explorer via RESTCONF
 219
 220 Go to
 221 `http://${ipaddress}:8181/apidoc/explorer/index.html <http://${ipaddress}:8181/apidoc/explorer/index.html>`__,
 222 sign in, and expand the FaaS panel. From there, users can execute
 223 various API calls to test their FaaS deployment such as create virtual
 224 container, create fabric, delete fabric, create/edit logical network
 225 elements.
 226
 227 Tutorials
 228 ---------
 229
 230 Below are tutorials for 4 major use cases.
 231
 232 1. to create and provision a fabric
 233
 234 2. to allocate resource from the fabric to a tenant
 235
 236 3. to define a logical network for a tenant. Currently there are two
 237    ways to create a logical network
 238
 239    a. Create a GBP (Group Based Policy) profile for a tenant and then
 240       convert it to a logical network via GBP FaaS render Or
 241
 242    b. Manually create a logical network via RESTCONF APIs.
 243
 244 4. to attach or detach an Endpoint to a logical switch or logical router
 245
 246 Create a fabric
 247 ~~~~~~~~~~~~~~~
 248
 249 Overview
 250 ^^^^^^^^
 251
 252 This tutorial walks users through the process of create a Fabric object
 253
 254 Prerequisites
 255 ^^^^^^^^^^^^^
 256
 257 A set of virtual switches (OVS) have to be registered or discovered by
 258 ODL. Mininet is recommended to create a OVS network. After an OVS
 259 network is created, set up the controller IP pointing to ODL IP address
 260 in each of the OVS. From ODL, a physical topology can be viewed via ODL
 261 DLUX UI or retrieved via RESTCONF API.
 262
 263 Instructions
 264 ^^^^^^^^^^^^
 265
 266 -  Run the OpenDaylight distribution and install odl-faas-all from the
 267    Karaf console.
 268
 269 -  Go to
 270    ***`http://${ipaddress}:8181/apidoc/explorer/index.html <http://${ipaddress}:8181/apidoc/explorer/index.html>`__***
 271
 272 -  Get the network topology after OVS switches are registered in the
 273    controller
 274
 275 -  Determine the nodes and links to be included in the to-be-defined
 276    Fabric object.
 277
 278 -  Execute create-fabric RESTCONF API with the corresponding JSON data
 279    as required.
 280
 281 Create virtual container for a tenant
 282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 283
 284 The purpose of this tutorial is to allocate network resources to a
 285 tenant
 286
 287 Overview
 288 ^^^^^^^^
 289
 290 This tutorial walks users through the process of create a Fabric
 291
 292 Prerequisites
 293 ^^^^^^^^^^^^^
 294
 295 1 or more fabric objects have been created.
 296
 297 Instructions
 298 ^^^^^^^^^^^^
 299
 300 -  Run the OpenDaylight karaf distribution and install odl-faas-all
 301    feature from the Karaf console. >feature:install odl-rest-conf
 302    odl-faas-all odl-mdsal-apidoc
 303
 304 -  Go to
 305    `http://${ipaddress}:8181/apidoc/explorer/index.html <http://${ipaddress}:8181/apidoc/explorer/index.html>`__
 306
 307 -  Execute create-vcontainer with the following restconf API with
 308    corresponding JSON data >
 309    `http://${ipaddress}:8181/restconf/operations/vcontainer-topology:create-vcontainer <http://${ipaddress}:8181/restconf/operations/vcontainer-topology:create-vcontainer>`__
 310
 311 After a virtual container is created, fabric resource and appliance
 312 resource can be assigned to the container object via the following
 313 RESTConf API.
 314
 315 -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-vfabric-to-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-vfabric-to-ld-node>`__
 316
 317 -  `http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-appliance-to-ld-node <http://${ipaddress}:8181/restconf/operations/vc-ld-node:add-appliance-to-ld-node>`__
 318
 319 Create a logical network
 320 ~~~~~~~~~~~~~~~~~~~~~~~~
 321
 322 Overview
 323 ^^^^^^^^
 324
 325 This tutorial walks users through the process of create a logical
 326 network for a tenant
 327
 328 Prerequisites
 329 ^^^^^^^^^^^^^
 330
 331 a virtual container has been created and assigned to the tenant
 332
 333 Instructions
 334 ^^^^^^^^^^^^
 335
 336 Currently there are two ways to create a logical network.
 337
 338 -  Option 1 is to use logical network RESTConf REST API and directly
 339    create individual network elements and connect them into a network
 340
 341 -  Option 2 is to define a GBP model and FaaS can map GBP model
 342    automatically into a logical network. Notes that for option 2, if the
 343    generated network requires some modification, we recommend modify the
 344    GBP model rather than change the network directly due to there is no
 345    synchronization from network back to GBP model in current release.
 346
 347 Manual Provisioning
 348 ^^^^^^^^^^^^^^^^^^^
 349
 350 To create a logical switch
 351
 352 -  `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-switches:logical-switches <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-switches:logical-switches>`__
 353    To create a logical router
 354
 355 -  `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-routers:logical-routers <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-routers:logical-routers>`__
 356    To attach a logical switch to a router
 357
 358    -  Step 1: updating/adding a port A on the logical switch
 359       `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-switches:logical-switches <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-switches:logical-switches>`__
 360
 361    -  Step 2: updating/adding a port B on the logical router
 362       `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-routers:logical-routers <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-routers:logical-routers>`__
 363
 364    -  Step 3; create a link between the port A and B
 365       `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-edges:logical-edges <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-edges:logical-edges>`__
 366
 367 -  To add security policies (ACL or SFC) on a port
 368    `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:faas-security-rules <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:faas-security-rules>`__
 369
 370 -  To query the logical network just created
 371    `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks>`__
 372
 373 Provision via GBP FaaS Render
 374 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 375
 376 -  Run the OpenDaylight distribution and install odl-faas-all and GBP
 377    faas render feature from the Karaf console.
 378
 379 -  Go to
 380    `http://${ipaddress}:8181/apidoc/explorer/index.html <http://${ipaddress}:8181/apidoc/explorer/index.html>`__
 381
 382 -  Execute "create GBP model" via GBP REST API. The GBP model then can
 383    be automatically mapped into a logical network.
 384
 385 Attach/detach an end point to a logical device
 386 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 387
 388 Overview
 389 ^^^^^^^^
 390
 391 This tutorial walks users through the process of registering an End
 392 Point to a logical device either logical switch or router. The purpose
 393 of this API is to inform the FaaS where an endpoint physically attach.
 394 The location information consists of the binding information between
 395 physical port identifier and logical port information. The logical port
 396 is indicated by the endpoint either Layer 2 attribute(MAC address) or
 397 Layer 3 attribute (IP address) and logical network ID (VLAN ID). The
 398 logical network ID is indirectly indicated the tenant ID since it is
 399 mutual exclusive resource allocated to a tenant.
 400
 401 Prerequisites
 402 ^^^^^^^^^^^^^
 403
 404 The logical switch to which those end points are attached has to be
 405 created beforehand. and the identifier of the logical switch is required
 406 for the following RESTCONF calls.
 407
 408 Instructions
 409 ^^^^^^^^^^^^
 410
 411 -  Run the OpenDaylight distribution and install odl-faas-all from the
 412    Karaf console.
 413
 414 -  Go to
 415    `http://${ipaddress}:8181/apidoc/explorer/index.html <http://${ipaddress}:8181/apidoc/explorer/index.html>`__
 416
 417 -  Execute "attach end point " with the following RESTCONF API and
 418    corresponding JSON data:
 419    `http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:faas-endpoints-locations <http://${ipaddress}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:faas-endpoints-locations>`__
 420