--- /dev/null
+== Fabric As A Service
+FaaS (Fabric As A service) has two layers of APIs. We describe the top level API in the user guide. This document focuses on the Fabric level API and describes each API's semantics and example implementation. The second layer defines an abstraction layer called '''Fabric''' API. The idea is to abstract network into a topology formed by a collections of fabric objects other than varies of physical devices.Each Fabric
+object provides a collection of unified services.The top level API enables application developers or users to write applications to map high level
+model such as GBP, Intent etc... into a logical network model, while the lower level gives the application more control to individual fabric object level. More importantly the Fabric API is more like SP (Service Provider API) a fabric provider or vendor can implement the SPI based on its own
+Fabric technique such as TRILL, SPB etc ...
+
+For how to use first level API operation, please refer to user guide for more details.
+
+=== FaaS Architecture
+
+FaaS Architecture is an 3 layered architecture, on the top is the FaaS Application layer, in the middle is the Fabric manager and at the bottom
+are different types of fabric objects. From bottom up, it is
+
+Fabric and its controller (Fabric Controller)::
+The Fabric object provides an abstraction of a homogeneous network or portion of the network and also has a built in Fabric controller
+which provides management plane and control plane for the fabric.
+The fabric controller implements the services required in Fabric Service and monitor and control the fabric operation.
+
+Fabric Manager::
+Fabric Manager manages all the fabric objects. also Fabric manager acts as a Unified Fabric Controller which provides inter-connect fabric control
+and configuration
+Also Fabric Manager is FaaS API service via Which FaaS user level logical network API (the top level API as mentioned previously)
+exposed and implemented.
+
+FaaS renderer for GBP (Group Based Policy)::
+FaaS renderer for GBP is an application of FaaS and provides the rendering service between GBP model and logical network model provided by
+Fabric Manager.
+
+=== Fabric APIs and Interfaces
+FaaS APIs have 4 groups as defined below
+
+Fabric Provisioning API::
+This set of APIs is used to create and remove Fabric Abstractions, in other words, those APIs is to provision the underlay networks and prepare to create overlay network(the logical network) on top of it.
+
+Fabric Service API::
+This set of APIs is used to create logical network over the Fabrics.
+
+EndPoint API::
+EndPoint API is used to bind a physical port which is the location of the attachment of an EndPoint happens or will happen.
+
+OAM API::
+Those APIs are for Operations, Administration and Maintenance purpose and In current release, OAM API is not implemented yet.
+
+==== Fabric Provisioning API
+* http://${IPADDRESS}:8181/restconf/operations/fabric:compose-fabric
+* http://${IPADDRESS}:8181/restconf/operations/fabric:decompose-fabric
+* http://${IPADDRESS}:8181/restconf/operations/fabric:get-all-fabrics
+
+==== Fabric Service API
+* RESTCONF for creating Logical port, switch, router, routing entries and link. Among them, both switches and routers have ports. links
+connect ports.these 5 logical elements are basic building blocks of a logical network.
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:create-logical-switch
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:rm-logical-switch
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:create-logical-router
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:rm-logical-router
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:add-static-route
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:create-logic-port
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:rm-logic-port
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:create-gateway
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:rm-gateway
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:port-binding-logical-to-fabric
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:port-binding-logical-to-device
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:add-port-function
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:add-acl
+** http://${IPADDRESS}:8181/restconf/operations/fabric-service:del-acl
+
+==== EndPoint API
+The following APIs is to bind the physical ports to the logical ports on the logical switches:
+
+* http://${IPADDRESS}:8181/restconf/operations/fabric-endpoint:register-endpoint
+* http://${IPADDRESS}:8181/restconf/operations/fabric-endpoint:unregister-endpoint
+* http://${IPADDRESS}:8181/restconf/operations/fabric-endpoint:locate-endpoint
+
+==== Others API
+* http://${IPADDRESS}:8181/restconf/operations/fabric-resource:create-fabric-port
+
+=== API Reference Documentation
+Go to http://${IPADDRESS}:8181/restconf/apidoc/index.html and expand on '''FaaS''' related panel for more APIs.
--- /dev/null
+== Fabric As A Service
+
+This document describes, from a user's or application's perspective, how to use the Fabric As A Service (FaaS)
+feature in OpenDaylight. This document contains configuration,
+administration, and management sections for the FaaS feature.
+
+=== Overview
+Currently network applications and network administrators mostly rely on lower level interfaces such as CLI,
+SNMP, OVSDB, NETCONF or OpenFlow to directly configure individual device for network service provisioning. In general, those interfaces are:
+
+* Technology oriented, not application oriented.
+* Vendor specific
+* Individual device oriented, not network oriented.
+* Not declarative, complicated and procedure oriented.
+
+To address the gap between application needs and network interface, there are a few application centric language proposed in OpenDaylight including Group Based Policy (GBP), Network Intent Composition (NIC), and NEtwork MOdeling (NEMO) trying to replace traditional southbound interface to application. Those languages are top-down abstractions and model application requirements in a more application-oriented way.
+
+After being involved with GBP development for a while, we feel the top down model still has a quite gap between the model and the underneath network since the existing interfaces to network devices lack of abstraction makes it very hard to map high level abstractions to the physical network. Often the applications built with these low level interfaces are coupled tightly with underneath technology and make the application's architecture monolithic, error prone and hard to maintain.
+
+We think a bottom-up abstraction of network can simplify, reduce the gap, and make it easy to implement the application centric model. Moreover in some uses cases, an interface with network service oriented are still desired for example from network monitoring/troubleshooting perspective. That's where the Fabric as a Service comes in.
+
+=== FaaS Architecture
+
+Fabric and its controller (Fabric Controller)::
+The Fabric object provides an abstraction of a homogeneous network or portion of the network and also has a built in Fabric controller which provides management plane and control plane for the fabric.
+The fabric controller implements the services required in Fabric Service and monitor and control the fabric operation.
+
+Fabric Manager::
+Fabric Manager manages all the fabric objects. also Fabric manager acts as a Unified Fabric Controller which provides inter-connect fabric control and configuration
+Also Fabric Manager is FaaS API service via Which FaaS user level logical network API (the top level API as mentioned previously) exposed and implemented.
+
+FaaS render for GBP (Group Based Policy)::
+FaaS render for GBP is an application of FaaS and provides the rendering service between GBP model and logical network model provided by Fabric Manager.
+
+=== FaaS RESTCONF API
+FaaS Provides two layers API:
+
+* The top layer is a **user level logical network** API which defines CRUD services operating on the following abstracted constructs:
+** vcontainer - virtual container
+** logical Port - a input/out/access point of a logical device
+** logical link - connects ports
+** logical switch - a layer 2 forwarding device
+** logical router - a layer 3 forwarding device
+** Subnet
+** Rule/ACL
+** End Points Registration
+** End Points Attachment
+
+Through these constructs, a logical network can be described without users knowing too much details about the physical network
+device and technology, i.e. users' network services is decoupled from underneath physical infrastructure. This decoupling brought the benefit that
+the users defined service is not locked in with any specific technology or physical devices. FaaS maps the logical network to the physical
+network configuration automatically which in maximum eliminates the manual provisioning work. As a result, human error is avoided and OPEX
+for network operators is massively reduced. Moreover migration from one technology to another is much easier to do and transparent to
+users' services.
+
+* The second layer defines an abstraction layer called **Fabric** API. The idea is to abstract network into a topology formed by a collections of
+fabric objects other than varies of physical devices.Each Fabric object provides a collection of unified services.
+The top level API enables application developers or users to write applications to map high level model such as GBP, Intent etc... into a logical
+network model, while the lower level gives the application more control to individual fabric object level. More importantly the Fabric API is more like SPI
+(Service Provider API) a fabric provider or vendor can implement the SPI based on its own Fabric technique such as TRILL, SPB etc ...
+
+This document is focused on the top layer API. For how to use second level API operation, please refer to FaaS developer guide for more details.
+
+NOTE: that for any JSON data or link not described here, please go to http://${IPADDRESS}:8181/apidoc/explorer/index.htm for details or clarification.
+
+=== Resource Management API
+The FaaS Resource Management API provides services to allocate and reclaim the network resources provided by Fabric object. Those APIs can
+be accessed via RESTCONF rendered from YANG in MD-SAL.
+
+* Name: Create virtual container
+** virtual container is an collections of resources allocated to a tenant, for example, a list of physical ports, bandwidth or L2 network or
+logical routers quantity. etc...
+** http://${IPADDRESS}:8181/restconf/operations/vcontainer-topology:create-vcontainer
+** Description: create a given virtual container.
+
+* Name: assign or remove fabric resource to a virtual container
+** http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:add-vfabric-to-ld-node
+** http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:rm-vfabric-to-ld-node
+
+* Name: assign or remove appliance to a virtual container
+** http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:add-appliance-to-ld-node
+** http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:rm-appliance-to-ld-node
+
+* Name: create or remove a child container
+** http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:create-child-ld-node
+** http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:rm-child-ld-node
+
+* RESTCONF path for Virtual Container Datastore query (note: vcontainer-id equals tenantID for now):
+** http://${IPADDRESS}:8181/restconf/config/network-topology/topology/{vcontainer-id}/vc-topology-attributes/
+** 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/{ld-node-id}/vc-ld-node-attributes
+
+
+=== Installing Fabric As A Service
+To install FaaS, download OpenDaylight and use the Karaf console
+to install the following feature:
+**odl-restconf**
+**odl-faas-all**
+**odl-groupbasedpolicy-faas** (if needs to use FaaS to render GBP)
+
+=== Configuring FaaS
+This section gives details about the configuration settings for various components in FaaS.
+
+The FaaS configuration files for the Karaf distribution are located in distribution/karaf/target/assembly/etc/faas
+
+* akka.conf
+** This file contains configuration related to clustering. Potential configuration properties can be found on the akka website at http://doc.akka.io
+* fabric-factory.xml
+* vxlan-fabric.xml
+* vxlan-fabric-ovs-adapter.xml
+** Those 3 files are used to initialize fabric module and located under distribution/karaf/target/assembly/etc/opendaylight/karaf
+
+=== Managing FaaS
+Start opendaylight karaf distribution
+
+* __>bin/karaf__
+Then
+From karaf console,Install features in the following order:
+* __>feature:Install odl-restconf__
+* __>feature:install odl-faas-all__
+* __>feature install odl-groupbasedpolicy-faas__
+
+After installing features above, users can manage Fabric resource and FaaS logical network channels from the APIDOCS explorer via RESTCONF
+
+Go to http://${IPADDRESS}:8181/apidoc/explorer/index.html, sign in, and expand the FaaS panel. From there, users can execute various API calls to test their FaaS deployment such as create virtual container, create fabric, delete fabric, create/edit logical network elements.
+
+=== Tutorials
+Below are tutorials for 4 major use cases.
+
+. to create and provision a fabric
+. to allocate resource from the fabric to a tenant
+. to define a logical network for a tenant. Currently there are two ways to create a logical network
+.. Create a GBP (Group Based Policy) profile for a tenant and then convert it to a logical network via GBP FaaS render Or
+.. Manually create a logical network via RESTCONF APIs.
+. to attach or detach an Endpoint to a logical switch or logical router
+
+==== Create a fabric
+===== Overview
+This tutorial walks users through the process of create a Fabric object
+
+===== Prerequisites
+A set of virtual switches (OVS) have to be registered or discovered by ODL. Mininet is recommended to create a OVS network.
+After an OVS network is created, set up the controller IP pointing to ODL IP address in each of the OVS.
+From ODL, a physical topology can be viewed via ODL DLUX UI or retrieved via RESTCONF API.
+
+===== Instructions
+* Run the OpenDaylight distribution and install odl-faas-all from the Karaf console.
+* Go to **__http://${IPADDRESS}:8181/apidoc/explorer/index.html__**
+* Get the network topology after OVS switches are registered in the controller
+* Determine the nodes and links to be included in the to-be-defined Fabric object.
+* Execute create-fabric RESTCONF API with the corresponding JSON data as required.
+
+==== Create virtual container for a tenant
+The purpose of this tutorial is to allocate network resources to a tenant
+
+===== Overview
+This tutorial walks users through the process of create a Fabric
+
+===== Prerequisites
+1 or more fabric objects have been created.
+
+===== Instructions
+* Run the OpenDaylight karaf distribution and install odl-faas-all feature from the Karaf console.
+>feature:install odl-rest-conf odl-faas-all odl-mdsal-apidoc
+* Go to http://${IPADDRESS}:8181/apidoc/explorer/index.html
+* Execute create-vcontainer with the following restconf API with corresponding JSON data
+> http://${IPADDRESS}:8181/restconf/operations/vcontainer-topology:create-vcontainer
+
+After a virtual container is created, fabric resource and appliance resource can be assigned to the container object via the following
+RESTConf API.
+
+* http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:add-vfabric-to-ld-node
+* http://${IPADDRESS}:8181/restconf/operations/vc-ld-node:add-appliance-to-ld-node
+
+==== Create a logical network
+===== Overview
+This tutorial walks users through the process of create a logical network for a tenant
+
+===== Prerequisites
+a virtual container has been created and assigned to the tenant
+
+===== Instructions
+Currently there are two ways to create a logical network.
+
+* Option 1 is to use logical network RESTConf REST API and directly create individual network elements and connect them into a network
+* Option 2 is to define a GBP model and FaaS can map GBP model automatically into a logical network.
+Notes that for option 2, if the generated network requires some modification, we recommend modify the GBP model rather than change the
+network directly due to there is no synchronization from network back to GBP model in current release.
+
+===== Manual Provisioning
+To create a logical switch
+
+* http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-switches:logical-switches
+To create a logical router
+* http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-routers:logical-routers
+To attach a logical switch to a router
+** Step 1: updating/adding a port A on the logical switch http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-switches:logical-switches
+** Step 2: updating/adding a port B on the logical router http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-routers:logical-routers
+** Step 3; create a link between the port A and B http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:logical-edges:logical-edges
+* To add security policies (ACL or SFC) on a port
+http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:faas-security-rules
+* To query the logical network just created
+http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks
+
+===== Provision via GBP FaaS Render
+* Run the OpenDaylight distribution and install odl-faas-all and GBP faas render feature from the Karaf console.
+* Go to http://${IPADDRESS}:8181/apidoc/explorer/index.html
+* Execute "create GBP model" via GBP REST API.
+The GBP model then can be automatically mapped into a logical network.
+
+==== Attach/detach an end point to a logical device
+===== Overview
+This tutorial walks users through the process of registering an End Point to a logical device either logical switch or router.
+The purpose of this API is to inform the FaaS where an endpoint physically attach. The location information consists of the binding information
+between physical port identifier and logical port information. The logical port is indicated by the endpoint either Layer 2 attribute(MAC address) or Layer 3 attribute (IP address) and logical network ID (VLAN ID). The logical network ID is indirectly indicated the tenant ID since it is mutual exclusive resource allocated to a tenant.
+
+===== Prerequisites
+The logical switch to which those end points are attached has to be created beforehand. and the identifier of the logical switch is required for the following RESTCONF calls.
+
+===== Instructions
+* Run the OpenDaylight distribution and install odl-faas-all from the Karaf console.
+* Go to http://${IPADDRESS}:8181/apidoc/explorer/index.html
+* Execute "attach end point " with the following RESTCONF API and corresponding JSON data:
+http://${IPADDRESS}:8181/restconf/configuration/faas-logical-networks:tenant-logical-networks:faas-endpoints-locations
Code Review / docs.git / commitdiff