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

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