OpenDaylight Controller:MD-SAL:MD-SAL Document Review:MD SAL
- 1 Contacts
- 2 Objective
- 3 What is it
- 3.1 Basic concepts
- 3.2 Messaging Patterns
- 3.3 Payload Types
- 3.4 Additional components
- 3.5 Assumed knowledge
- 3.6 Assumed Environment
- 3.7 WHY DO WE HAVE IT?
- 3.8 PAINPOINTS
- 3.9 HOW DOES IT WORK?
- 3.10 Who should use it?
- 4 EDUCATION
- 5 EXAMPLES/TUTORIALS
- 6 Meetings/Action Items/Progress
- Owner: Tony Tkacik <email@example.com>
The Model-Driven SAL (MD-SAL) is an infrastructure component that provides messaging and data storage functionality based on data and interface models defined by application developers (i.e. user-defined models).
MD-SAL has two main objectives:
- Define a common-layer, concepts, data model building blocks and patterns that provide an infrastructure/framework for applications and inter-application communication.
- Provide support for user-defined transport and payload formats, including payload serialization and adaptation (e.g. binary, XML or JSON).
To achieve the above objectives, MD-SAL uses YANG as the modeling language for both interface and data definitions, and provides a messaging and data-centric runtime for such services based on YANG modeling.
MD-SAL extends the YANGTools project (which provides a YANG parser, data structures, and data supporting functionality) with messaging patterns and the concept of data stores / data brokers.
What is it
MD-SAL is a home-grown message-bus inspired extensible middleware, which uses YANG modeling language to describe data and messaging patterns between applications.
Model-driven nature of MD-SAL allows for behind-the-scene API and payload type mediation and transformation to facilitate seamless communication between applications. It also allows for other applications to provide connectors / expose different set of APIs and derive most of its functionality purely from YANG Model, which all existing code without modification could benefit from (one such example is RESTCONF Connector), which is application built on top of MD-SAL and exposes YANG-modeled application APIs transparently via HTTP and adds support for XML and JSON payload type.)
Basic concepts are building blocks which are used by applications, and from which MD-SAL derives its services and behaviour based on mapping of basic concepts to developer-supplied YANG models.
- Data Tree - All state-related data are modeled and represented as data tree, with possibility to address any element / subtree
- Operational Data Tree - Reported state of the system, published by the providers using MD-SAL. Represents a feedback loop for applications to observe state of the network / system.
- Configuration Data Tree - Intended state of the system or network, populated by consumers, which expreses their intention.
- Instance Identifier - Unique identifier of node / subtree in data tree, which provides unambiguous information, how to retrieve node / subtree from conceptual data trees.
- Notification - Asynchronous transient event (from perspective of provider) which may be consumed by consumers and they may act upon it
- RPC - asynchronous request-reply message pair, when request is triggered by consumer, send to the provider, which in future replies with reply message.
MD-SAL provides several messaging patterns, which are intended to transfer YANG modeled data between applications to provide data-centric integration between applications instead of API-centric integration.
- Unicast communication
- RPC - unicast between consumer and provider, where consumer sends request message to provider, which asynchronously responds with reply message
- Publish / Subscribe
- Transactional reads from conceptual data tree - read-only transactions
- Transactional modification to conceptual data tree - write transactions
- Transaction Chaining
- Data Change Events
Currently core of MD-SAL exposes two Java API / payload types:
- **YANG Java Binding APIs** (binding) - Java interfaces and transfer objects generated in compile-time from YANG model, which allows for easy development of application tailored to specific models.
- DOM APIs (dom) - XML DOM inspired payload format, which is more suitable for components, which interprets model and could provide functionality from any valid YANG model (e.g. RESTCONF, data store, Netconf).
By extension MD-SAL (via use of RESTCONF Connector) also provides REST APIs for any YANG-modeled application. See RESTCONF for more information.
In addition to core MD-SAL which provides implementation of core functionality for intra-process communication and API and payload format translation projects provides additional components:
- RESTCONF Connector - model-driven HTTP APIs to MD-SAL and applications integrated with MD-SAL, based on draft-bierman-netconf-restconf-02.
- Java programming
- YANG Modelling language
- Java 7
WHY DO WE HAVE IT?
- pain points addressed
- problems solved
HOW DOES IT WORK?
The data handling functionality is separated into two distinct brokers: a binding-independent DOM Broker that interprets YANG models at runtime and is the core component of the MD-SAL runtime, and a Binding-Aware Broker that exposes Java APIs for plugins using binding-aware representation of data (Java DTOs). These brokers, along with their supporting components are shown in the following figure: The DOM Broker uses YANG data APIs to describe data and Instance Identifiers specific to YANG to describe paths to data in the system. Data structures in the Binding-Aware Broker that are visible to applications are generated from YANG models in YANG tools. The DOM Broker relies on presence of YANG schemas, which are interpreted at runtime for functionality-specific purposes, such as RPC routing, data store organization, and validation of paths.
The Binding-Aware Broker relies on Java APIs, which are generated from YANG models, and on common properties of Java DTOs, which are enforced by code generation. Therefore data transfer optimizations (zero-copy) are possible when a data Consumer and a data Provider are both Binding-Aware.
The Binding-Aware Broker connects to the DOM Broker through the BA-BI Connector, so that Binding-Aware Consumer/Provider applications/plugins can communicate with their respective binding-independent counterparts. The BA-BI Connector, together with the Mapping Service, the Schema Service, the Codec Registry and the Codec Generator implement dynamic late binding: the codecs that translate YANG data representations between a binding-independent (DOM) format and DTOs, which are specific to Java bindings, are auto-generated on demand.
The physical Data Store is pluggable – MD-SAL provides an SPI through which different data store implementations can be plugged in.
The Mount concept and the support for APIs generated from models allow for applications talking to NETCONF devices to be compiled directly against device models – there is no need for controller-level models that represent devices. Device models are loaded into the controller from a NETCONF device when the controller connects to the device, and apps can work directly with them.
HOW DOES IT FIT INTO THE CONTROLLER ARCHITECTURE?
MD-SAL is core integration layer, which provides inter-application communication.
Who should use it?
MD-SAL is targeted for developers, which develops applications / protocol plugins to be run in JVM in same process as rest of the system.
WHICH PROJECTS DO/DON'T USE IT?
- Almost every Opendaylight project does use it, except Yangtools which provides infrastructure for it.
MD-SAL and ODL App Tutorials
- Toaster Tutorial
- Toaster Step-By-Step
- Learning Switch Tutorial
- Simple TCP Ping Plugin
- MD-SAL Q&A (a tutorial by Ciena)
- AD-SAL / MD-SAL Comparison (a tutorial by Ciena)
- MD-SAL Simple Archetype
- Yet Another MD-SAL Simple Archetype Tutorial
Tutorial Videos on YouTube
- YouTube: 5 Minute or less ODL Tutorials : a set of excellent short tutorials covering various aspects of ODL (config subsystem for now)
- Youtube: Developers: Intro to OpenDaylight
MD-SAL How Tos - Quick Code Snippets (Tutorials by Ciena)
- How To Insert Data In MD-SAL Data Store (outdated)
- How To Register A Service To MD-SAL
- How To Publish Notifications To MD-SAL
- How To Handle Notifications Published To MD-SAL
- How To Access Data In MD-SAL From MountPoint
- How To Look Up Data In MD-SAL
- How To Publish Node To MD-SAL
- How To Publish NodeConnector To MD-SAL
- How To Publish Link To MD-SAL
- How To Remove Node From MD-SAL
- How To Remove NodeConnector From MD-SAL
- How To Remove Link From MD-SAL
- How To Look Up Topology and Links In MD-SAL
- How to Lookup all NodeConnectors of a Node in MD-SAL
- How MD-SAL Identifies Southbound Plugin For Flow Provisioning
Note* - Some of the above code snippets work for hydrogen release and are deprecated for helium. I am currently working on writing code snippets for helium and will be updated here soon.
- Yang Central: the first section lists a bunch of tutorials.
- Netconf Central: this is more netconf oriented, but still contains a lot of yang-related information
- Tail-F: a yang overview paper:
- A Netconf/Yang Tutorial by Tail-F
- IETF Netconf wiki: contains a list if Netconf/Yang pointers
- YANG modeling tutorial (pyang)
- Pyang-based validation scripts, presented at Dev Design Summit
ALTERNATIVES (INVESTIGATED OR POSSIBLE)
- Alternatives to current approach
- See learning resources section