Jump to: navigation, search

OpenDaylight Controller:MD-SAL:FAQ

Q-1: What is the overall MD-SAL architecture?
  • What is the overall architecture, components, and functionality?
  • Who supplies which components, and how are the components plumbed?


The overall Model-Driven SAL (MD-SAL) architecture did not really change from the API-Driven SAL (AD-SAL). As with the AD-SAL, plugins can be data providers, or data consumers, or both (although the AD-SAL did not explicitly name them as such). Just like the AD-SAL, the MD-SAL connects data consumers to appropriate data providers and (optionally) facilitates data adaptation between them.
Now, in the AD-SAL, the SAL APIs request routing between consumers and providers, and data adaptations are all statically defined at compile or build time. In the MD-SAL, the SAL APIs and request routing between consumers and providers are defined from models, and data adaptations are provided by 'internal' adaptation plugins. The API code is generated from models when a plugin is compiled. When the plugin OSGI bundle is loaded into the controller, the API code is loaded into the controller along with the rest of the plugin containing the model.
The AD-SAL and the MD-SAL are shown side-by-side in the following figure:


The AD-SAL provides request routing (selects an SB plugin based on service type), and optionally, provides service adaptation, if an NB (Service, abstract) API is different from its corresponding SB (protocol) API. For example, in the above figure, the AD-SAL routes requests from NB-Plugin 1 to SB Plugins 1 and 2. Note that the plugin SB and NB APIs in this example are essentially the same (although both of them need to be defined). Request routing is based on the plugin type: the SAL knows which node instance is served by which plugin. When an NB Plugin requests an operation on a given node, the request is routed to the appropriate plugin which then routes the request to the appropriate node. The AD-SAL can also provide service abstractions and adaptations. For example, in the above figure, NB Plugin 2 is using an abstract API to access the services provided by SB Plugins 1 and 2. The translation between the SB Plugin API and the abstract NB API is done in the Abstraction module in the AD-SAL.
The MD-SAL provides request routing and the infrastructure to support service adaptation. However, it does not provide service adaptation itself: service adaptation is provided by plugins. From the point of view of MD-SAL, the Adaptation Plugin is a regular plugin. It provides data to the SAL, and consumes data form the SAL through APIs generated from models. An Adaptation Plugin basically performs model-to-model translations between two APIs. Request Routing in the MD-SAL is done on both protocol type and node instances, since node instance data is exported from the plugin into the SAL (the model data contains routing information).
The simplest MD-SAL APIs generated from models (RPCs and Notifications, both supported in the yang modeling language) are functionally equivalent to AD-SAL function call APIs. Additionally, the MD-SAL can store data for models defined by plugins. Provider and consumer plugins can exchange data through the MD-SAL storage (more details in later sections). Data in the MD-SAL is accessed through getter and setter APIs generated from models. Note that this is in contrast to the AD-SAL, which is stateless.
Note that in the above figure, both NB AD-SAL Plugins provide REST APIs to the controller client applications.
The functionality provided by the MD-SAL is basically to facilitate the plumbing between providers and consumers. A provider or a consumer can register itself with the MD-SAL. A consumer can find a provider that it is interested in. A provider can generate notifications; a consumer can receive notifications and issue RPCs to get data from providers. A provider can insert data into SAL’s storage; a consumer can read data from SAL’s storage.
Note that the structure of SAL APIs in the MD-SAL is different from that in the AD-SAL. The AD-SAL typically has both NB and SB APIs even for functions or services that are mapped 1:1 between SB Plugins and NB Plugins. For example, in the current AD-SAL implementation of the OpenFlow Plugin and applications, the NB SAL APIs used by OF applications are mapped 1:1 onto SB OF Plugin APIs. The MD-SAL allows both the NB plugins and SB plugins to use the same API generated from a model. One plugin becomes an API (service) provider; the other becomes an API (service) consumer. This eliminates the need to define two different APIs and to provide three different implementations even for the cases where the APIs are mapped to each other 1:1. The MD SAL provides instance-based request routing between multiple provider plugins.
Q-2: What functionality does the MD-SAL assume? For example, does the SAL assume that the network model is a part of the SAL?


The MD-SAL does not assume any model. All models are provided by the plugins. The MD-SAL only provides the infrastructure and the plumbing for the plugins.
Q-3: What is a "day in the life" of an MD-SAL plugin?
All plugins (protocol, application, adaptation, and others) have the same life-cycle. The life of a plugin has two distinct phases: design and operation.
During the design phase, the plugin designer performs the following actions:
  • The designer decides which data will be consumed by the plugin and imports the SAL APIs generated from the models of the API provider. Note that the topology model is just one possible data type that may be consumed by a plugin. The list of currently available data models and their APIs can be found in YANG_Tools:Available_Models.
  • The designer decides which data and how will be provided by the plugin and designs the data model for the provided data. The data model (expressed in yang) is then run through the yang tools, which generate the SAL APIs for the model.
  • The implementations for the generated consumer and provider APIs, along with other plugin features and functionality, are developed. The resulting code is packaged in a “plugin” OSGI bundle. Note that a developer may package the code of a subsystem in multiple plugins or applications that may communicate with each other through the SAL.
  • The generated APIs and a set of helper classes are also built and packaged in an “API” OSGI bundle.
A-3: (i) Plugin Development Process
The plugin development process is shown in the following figure.

Plugin design process.png

When the OSGI bundle of a plugin is loaded into the controller and activated, the operation phase begins. The plugin operation is probably best explained with a few examples describing the operation of the OF Protocol plugin and OF applications, such as the Flow Programmer Service, the ARP Handler, or the Topology Manager.
A-3: (ii) "Flow Deleted" notification scenario
The following figure shows a scenario where a “Flow Deleted” notification from a switch arrives at the controller.

Flow Deleted use case.png

The scenario is as follows:
  1. The Flow Programmer Service registers with the MD SAL for the “Flow Deleted” notification. This is done when the controller and its plugins or applications are started.
  2. A “Flow Deleted” OF packet arrives at the controller. The OF Library receives the packet on the TCP/TLS connection to the switch that is sending and passes it to the OF Plugin.
  3. The OF Plugin parses the packet and uses the parsed data to create a “Flow Deleted” SAL notification. The notification is actually an immutable “Flow Deleted” Data Transfer Object (DTO) that is created or populated by means of methods from the model-generated OF Plugin API.
  4. The OF Plugin sends the “Flow Deleted” SAL notification (containing the notification DTO) into the SAL. The SAL routes the notification to registered consumers, in this case, the Flow Programmer Service.
  5. The Flow Programmer Service receives the notification containing the notification DTO.
  6. The Flow Programmer Service uses methods from the model-generated OF Plugin API to get the data from the immutable notification DTO received in Step 5. The processing is the same as in the AD-SAL.
Note that other packet-in scenarios, where a switch punts a packet to the controller, such as an ARP or an LLDP packet, are similar. Interested apps register for the respective notifications. The OF plugin generates the notification from the received OF packets, and sends them to the SAL. The SAL routes the notifications to the registered recipients.
A-3: (iii) "Add Flow" scenario via NB REST API invocation
The following figure shows a scenario where an external application adds a flow by means of the NB REST API of the controller.

Add Flow use case.png

The scenario is as follows:
  1. Registrations are performed when the controller and its plugins or applications are started. a)The Flow Programmer Service registers with the MD SAL for Flow configuration data notifications, and b) The OF Plugin registers (among others) the ‘AddFlow’ RPC implementation with the SAL. Note that the RPC is defined in the OF Plugin model, and that the API is generated during build time.
  2. A client application requests a flow add through the REST API of the controller. (Note that in the AD-SAL, there is a dedicated NB REST API on top of the Flow Programming Service. The MD-SAL provides a common infrastructure where data and functions defined in models can be accessed by means of a common REST API. For more information, see http://datatracker.ietf.org/doc/draft-bierman-netconf-restconf/). The client application provides all parameters for the flow in the REST call.
  3. Data from the ‘Add Flow’ request is deserialized, and a new flow is created in the Flow Service configuration data tree. (Note that in this example, the configuration and operational data trees are separated; this may be different for other services). Note also that the REST call returns success to the caller as soon as the flow data is written to the configuration data tree.
  4. Since the Flow Programmer Service is registered to receive notifications for data changes in the Flow Service data tree, the MD-SAL generates a ‘data changed’ notification to the Flow Programmer Service.
  5. The Flow Programmer Service reads the newly added flow, and performs a flow add operation (which is basically the same as in the AD-SAL).
  6. At some point during the flow addition operation, the Flow Programmer Service needs to tell the OF Plugin to add the flow in the appropriate switch. The Flow Programmer Service uses the OF Plugin generated API to create the RPC input parameter DTO for the “AddFlow” RPC of the OF Plugin.
  7. The Flow Programmer Service gets the service instance (actually, a proxy), and invokes the “AddFlow” RPC on the service. The MD-SAL will route the request to the appropriate OF Plugin (which implements the requested RPC).
  8. The “AddFlow” RPC request is routed to the OF Plugin, and the implementation method of the “AddFlow” RPC is invoked.
  9. The “AddFlow” RPC implementation uses the OF Plugin API to read values from the DTO of the RPC input parameter. (Note that the implementation will use the getter methods of the DTO generated from the yang model of the RPC to read the values from the received DTO.)
  10. The "AddFlow" RPC is further processed (pretty much the same as in the AD-SAL) and at some point, the corresponding flowmod is sent to the corresponding switch.
Q-4: Is there a document that describes how code is generated from the models for the MD-SAL?


Yangtools documents the Yang to Java generation: YANG_Tools:YANG_to_Java_Mapping, including examples of how the yang constructs are mapped onto Java classes. You can write unit tests against the generated code. You will have to write the implementations of the generated RPC interfaces. The generated code is just Java, and it debugs just like Java.
If you want to play with generating Java from Yang there is a Maven archetype to help you get going: Maven_Archetypes:odl-model-project.
Or, you can try creating a project in Eclipse as explained on Eclipse Setup (see also older external documentation on sdntutorials.com about How to create Maven project in Eclipse.)
Q-5: The code generation tools mention 'producers' and 'consumers'. How are these related to 'southbound' and 'northbound SAL plugins?


The difference between southbound and northbound plugins is that the southbound plugins talk protocols to network nodes and northbound plugins talk application APIs to the controller applications. As far as the SAL is concerned, there is really no north or south. The SAL is basically a data exchange and adaptation mechanism between plugins. The plugin SAL roles (consumer or producer) are defined with respect to the data being moved around or stored by the SAL. A producer implements an API and provides the data of the API: a consumer uses the API and consumes the data of the API.
While 'northbound' and 'southbound' provide the view of the SAL of a network engineer, 'consumer' and 'producer' provide the view of the SAL of a software engineer, and is shown in the following figure:


Q-6: Where can I find models that have already been defined in OpenDaylight?


The list of models that have been defined for the SAL and in the various plugins can be found in OpenDaylight_Controller:MD-SAL:Model_Reference.
Q-7: How do I migrate my existing plugins and services to MD-SAL?


The migration guide can be found in OpenDaylight_Controller:MD-SAL:Application_Migration_Guide.

Q-8: Where can I find SAL example code?


We provided a simple complete example of a model, a service provider (toaster) and a service consumer in the toaster sample. It provides the model of a programmable toaster, a sample consumer application that uses MD-SAL APIs, a sample southbound plugin (a service provider) that implements toaster, and a unit test suite.
The toaster example is in controller.git under opendaylight/md-sal/samples.
Q-9: Where is the REST API code for the example?


The REST APIs will be derived from models. You do not have to write any code for it. The controller will implement the RESTCONF protocol which defines access to yang-formatted data through REST. Basically, all you need to do is define your service in a model, and expose that model to the SAL. REST access to your modeled data will then be provided by the SAL infrastructure. However, if you want to, you can create your own REST API (for example, to be compliant with an existing API).
Q-10: How can one use RESTCONF to access the MD-SAL datastore?


For information on accessing the MD-SAL datastore, see OpenDaylight_Controller:MD-SAL:Restconf.