-== OVSDB MDSAL Southbound Plugin Developer Guide
+== OVSDB MD-SAL Southbound Plugin Developer Guide
=== Overview
-TBD
+The Open vSwitch Database (OVSDB) Model Driven Service Abstraction Layer
+(MD-SAL) Southbound plugin provides an MD-SAL based interface to
+Open vSwitch systems. This is done by augmenting the MD-SAL topology node with
+a YANG model which replicates some (but not all) of the Open vSwitch schema.
-=== OVSDB MDSAL Southbound Plugin Architecture
-TBD
+=== OVSDB MD-SAL Southbound Plugin Architecture and Operation
+The architecture and operation of the OVSDB MD-SAL Southbound plugin is
+illustrated in the following set of diagrams.
-=== Key APIs and Interfaces
-TBD
+==== Connecting to an OVSDB Node
+An OVSDB node is a system which is running the OVS software and is capable of
+being managed by an OVSDB Manager. The OVSDB MD-SAL Southbound plugin in
+OpenDaylight is capable of operating as an OVSDB manager. Depending on the
+configuration of the OVSDB node, the connection of the OVSDB manager can
+be active or passive.
+
+===== Active OVSDB Node Manager Workflow
+An active OVSDB node manager connection is made when OpenDaylight initiates the
+connection to the OVSDB node. In order for this to work, you must configure the
+OVSDB node to listen on a TCP port for the connection (i.e.
+OpenDaylight is active and the OVSDB node is passive). This option can be
+configured on the OVSDB node using the following command:
+
+ ovs-vsctl set-manager ptcp:6640
+
+The following diagram illustrates the sequence of events which occur when
+OpenDaylight initiates an active OVSDB manager connection to an OVSDB node.
+
+.Active OVSDB Manager Connection
+image::ovsdb-sb-active-connection.jpg[width=500]
+
+Step 1::
+Create an OVSDB node by using RESTCONF or an OpenDaylight plugin. The OVSDB node
+is listed under the OVSDB topology node.
+Step 2::
+Add the OVSDB node to the OVSDB MD-SAL southbound configuration datastore. The
+OVSDB southbound provider is registered to listen for data change events on the
+portion of the MD-SAL topology data store which contains the OVSDB southbound
+topology node augmentations. The addition of an OVSDB node causes an event which
+is received by the OVSDB Southbound provider.
+Step 3::
+The OVSDB Southbound provider initiates a connection to the OVSDB node using
+the connection information provided in the configuration OVSDB node (i.e. IP
+address and TCP port number).
+Step 4::
+The OVSDB Southbound provider adds the OVSDB node to the OVSDB MD-SAL
+operational data store. The operational data store contains OVSDB node
+objects which represent active connections to OVSDB nodes.
+Step 5::
+The OVSDB Southbound provider requests the schema and databases which are
+supported by the OVSDB node.
+Step 6::
+The OVSDB Southbound provider uses the database and schema information to
+construct a monitor request which causes the OVSDB node to send the controller
+any updates made to the OVSDB databases on the OVSDB node.
+
+
+===== Passive OVSDB Node Manager Workflow
+A passive OVSDB node connection to OpenDaylight is made when the OVSDB node
+initiates the connection to OpenDaylight. In order for this to work, you must
+configure the OVSDB node to connect to the IP address and OVSDB port on which
+OpenDaylight is listening. This option can be configured on the OVSDB node
+using the following command:
+
+ ovs-vsctl set-manager tcp:<IP address>:6640
+
+The following diagram illustrates the sequence of events which occur when an
+OVSDB node connects to OpenDaylight.
+
+.Passive OVSDB Manager Connection
+image::ovsdb-sb-passive-connection.jpg[width=500]
+
+Step 1::
+The OVSDB node initiates a connection to OpenDaylight.
+Step 2::
+The OVSDB Southbound provider adds the OVSDB node to the OVSDB MD-SAL
+operational data store. The operational data store contains OVSDB node
+objects which represent active connections to OVSDB nodes.
+Step 3::
+The OVSDB Southbound provider requests the schema and databases which are
+supported by the OVSDB node.
+Step 4::
+The OVSDB Southbound provider uses the database and schema information to
+construct a monitor request which causes the OVSDB node to send back
+any updates which have been made to the OVSDB databases on the OVSDB node.
+
+==== OVSDB Node ID in the Southbound Operational MD-SAL
+When OpenDaylight initiates an active connection to an OVSDB node, it
+writes an external-id to the Open_vSwitch table on the OVSDB node. The
+external-id is an OpenDaylight instance identifier which identifies the
+OVSDB topology node which has just been created.
+Here is an example showing the value of the 'opendaylight-iid' entry
+in the external-ids column of the Open_vSwitch table where the
+node-id of the OVSDB node is 'ovsdb:HOST1'.
+
+ $ ovs-vsctl list open_vswitch
+ ...
+ external_ids : {opendaylight-iid="/network-topology:network-topology/network-topology:topology[network-topology:topology-id='ovsdb:1']/network-topology:node[network-topology:node-id='ovsdb:HOST1']"}
+ ...
+
+The 'opendaylight-iid' entry in the external-ids column of the Open_vSwitch
+table causes the OVSDB node to have same node-id in the operational
+MD-SAL datastore as in the configuration MD-SAL datastore. This holds true
+if the OVSDB node manager settings are subsequently changed so that a
+passive OVSDB manager connection is made.
+
+If there is no 'opendaylight-iid' entry in the external-ids column and
+a passive OVSDB manager connection is made, then the node-id of the OVSDB
+node in the operational MD-SAL datastore will be constructed using the UUID
+of the Open_vSwitch table as follows.
+
+ "node-id": "ovsdb://uuid/b8dc0bfb-d22b-4938-a2e8-b0084d7bd8c1"
+
+The 'opendaylight-iid' entry can be removed from the Open_vSwitch table using
+the following command.
+
+ $ sudo ovs-vsctl remove open_vswitch . external-id "opendaylight-iid"
+
+==== OVSDB Changes by using OVSDB Southbound Config MD-SAL
+After the connection has been made to an OVSDB node, you can make changes to the
+OVSDB node by using the OVSDB Southbound Config MD-SAL. You can
+make CRUD operations by using the RESTCONF interface or by a plugin
+using the MD-SAL APIs. The following diagram illustrates the highlevel flow of
+events.
+
+.OVSDB Changes by using the Southbound Config MD-SAL
+image::ovsdb-sb-config-crud.jpg[width=500]
+
+Step 1::
+A change to the OVSDB Southbound Config MD-SAL is made. Changes include adding
+or deleting bridges and ports, or setting attributes of OVSDB nodes, bridges or
+ports.
+Step 2::
+The OVSDB Southbound provider receives notification of the changes made to the
+OVSDB Southbound Config MD-SAL data store.
+Step 3::
+As appropriate, OVSDB transactions are constructed and transmitted to the OVSDB
+node to update the OVSDB database on the OVSDB node.
+Step 4::
+The OVSDB node sends update messages to the OVSDB Southbound provider to
+indicate the changes made to the OVSDB nodes database.
+Step 5::
+The OVSDB Southbound provider maps the changes received from the OVSDB node
+into corresponding changes made to the OVSDB Southbound Operational
+MD-SAL data store.
+
+==== Detecting changes in OVSDB coming from outside OpenDaylight
+Changes to the OVSDB nodes database may also occur independently of OpenDaylight.
+OpenDaylight also receives notifications for these events and updates the
+Southbound operational MD-SAL. The following diagram illustrates the sequence
+of events.
+
+.OVSDB Changes made directly on the OVSDB node
+image::ovsdb-sb-oper-crud.jpg[width=500]
+
+Step 1::
+Changes are made to the OVSDB node outside of OpenDaylight (e.g. ovs-vsctl).
+Step 2::
+The OVSDB node constructs update messages to inform OpenDaylight of the changes
+made to its databases.
+Step 3::
+The OVSDB Southbound provider maps the OVSDB database changes to corresponding
+changes in the OVSDB Southbound operational MD-SAL data store.
+
+// ==== OpenFlow controller
+// Discussion of how the OpenFlow controller node is associated with the OVSDB
+// southbound model
==== OVSDB Model
-TBD
+The OVSDB Southbound MD-SAL operates using a YANG model which is based on the
+abstract topology node model found in the
+https://github.com/opendaylight/yangtools/blob/stable/lithium/model/ietf/ietf-topology/src/main/yang/network-topology%402013-10-21.yang[network topology model].
+
+The augmentations for the OVSDB Southbound MD-SAL are defined in the
+https://github.com/opendaylight/ovsdb/blob/stable/lithium/southbound/southbound-api/src/main/yang/ovsdb.yang[ovsdb.yang] file.
+
+There are three augmentations:
+
+*ovsdb-node-augmentation*::
+This augments the topology node and maps primarily to the Open_vSwitch table of
+the OVSDB schema. It contains the following attributes.
+ * *connection-info* - holds the local and remote IP address and TCP port numbers for the OpenDaylight to OVSDB node connections
+ * *db-version* - version of the OVSDB database
+ * *ovs-version* - version of OVS
+ * *list managed-node-entry* - a list of references to ovsdb-bridge-augmentation nodes, which are the OVS bridges managed by this OVSDB node
+ * *list datapath-type-entry* - a list of the datapath types supported by the OVSDB node (e.g. 'system', 'netdev') - depends on newer OVS versions
+ * *list interface-type-entry* - a list of the interface types supported by the OVSDB node (e.g. 'internal', 'vxlan', 'gre', 'dpdk', etc.) - depends on newer OVS verions
+ * *list openvswitch-external-ids* - a list of the key/value pairs in the Open_vSwitch table external_ids column
+ * *list openvswitch-other-config* - a list of the key/value pairs in the Open_vSwitch table other_config column
+*ovsdb-bridge-augmentation*::
+This augments the topology node and maps to an specific bridge in the OVSDB
+bridge table of the associated OVSDB node. It contains the following attributes.
+ * *bridge-uuid* - UUID of the OVSDB bridge
+ * *bridge-name* - name of the OVSDB bridge
+ * *bridge-openflow-node-ref* - a reference (instance-identifier) of the OpenFlow node associated with this bridge
+ * *list protocol-entry* - the version of OpenFlow protocol to use with the OpenFlow controller
+ * *list controller-entry* - a list of controller-uuid and is-connected status of the OpenFlow controllers associated with this bridge
+ * *datapath-id* - the datapath ID associated with this bridge on the OVSDB node
+ * *datapath-type* - the datapath type of this bridge
+ * *fail-mode* - the OVSDB fail mode setting of this bridge
+ * *flow-node* - a reference to the flow node corresponding to this bridge
+ * *managed-by* - a reference to the ovsdb-node-augmentation (OVSDB node) that is managing this bridge
+ * *list bridge-external-ids* - a list of the key/value pairs in the bridge table external_ids column for this bridge
+ * *list bridge-other-configs* - a list of the key/value pairs in the bridge table other_config column for this bridge
+*ovsdb-termination-point-augmentation*::
+This augments the topology termination point model. The OVSDB Southbound
+MD-SAL uses this model to represent both the OVSDB port and OVSDB interface for
+a given port/interface in the OVSDB schema. It contains the following
+attributes.
+ * *port-uuid* - UUID of an OVSDB port row
+ * *interface-uuid* - UUID of an OVSDB interface row
+ * *name* - name of the port
+ * *interface-type* - the interface type
+ * *list options* - a list of port options
+ * *ofport* - the OpenFlow port number of the interface
+ * *ofport_request* - the requested OpenFlow port number for the interface
+ * *vlan-tag* - the VLAN tag value
+ * *list trunks* - list of VLAN tag values for trunk mode
+ * *vlan-mode* - the VLAN mode (e.g. access, native-tagged, native-untagged, trunk)
+ * *list port-external-ids* - a list of the key/value pairs in the port table external_ids column for this port
+ * *list interface-external-ids* - a list of the key/value pairs in the interface table external_ids interface for this interface
+ * *list port-other-configs* - a list of the key/value pairs in the port table other_config column for this port
+ * *list interface-other-configs* - a list of the key/value pairs in the interface table other_config column for this interface
+
+=== Examples of OVSDB Southbound MD-SAL API
+
+==== Connect to an OVSDB Node
+This example RESTCONF command adds an OVSDB node object to the OVSDB
+Southbound configuration data store and attempts to connect to the OVSDB host
+located at the IP address 10.11.12.1 on TCP port 6640.
+
+ POST http://<host>:8181/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+ Content-Type: application/json
+ {
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ "connection-info": {
+ "ovsdb:remote-ip": "10.11.12.1",
+ "ovsdb:remote-port": 6640
+ }
+ }
+ ]
+ }
+
+==== Query the OVSDB Southbound Configuration MD-SAL
+Following on from the previous example, if the OVSDB Southbound configuration
+MD-SAL is queried, the RESTCONF command and the resulting reply is similar
+to the following example.
+
+ GET http://<host>:8080/restconf/config/network-topology:network-topology/topology/ovsdb:1/
+ Application/json data in the reply
+ {
+ "topology": [
+ {
+ "topology-id": "ovsdb:1",
+ "node": [
+ {
+ "node-id": "ovsdb:HOST1",
+ "ovsdb:connection-info": {
+ "remote-port": 6640,
+ "remote-ip": "10.11.12.1"
+ }
+ }
+ ]
+ }
+ ]
+ }
-==== Tunnel Overlay Model
-TBD
+// ==== Query the OVSDB Southbound Operational MD-SAL
+// If the previous example POST command is successful in connecting to the OVSDB
+// node, then eventually the OVSDB Southbound operational MD-SAL is populated
+// with information received in an OVSDB update message from the OVSDB node. The
+// RESTCONF query and resulting reply is similar to the following example.
+//
+// http://<host>:8080/restconf/operational/network-topology:network-topology/topology/ovsdb:1/
+//
+// Application/json data in the reply
+// TBD - things not working well at time of writing
+//
+//
+//
+// ==== Add a bridge
+// TBD
+//
+// ==== Add a port
+// TBD
+//
+// ==== Set attributes
+// TBD
+//
+// ==== Delete examples
+// TBD
-=== API Reference Documentation
-TBD
+=== Reference Documentation
+http://openvswitch.org/ovs-vswitchd.conf.db.5.pdf[Openvswitch schema]
Code Review / docs.git / commitdiff
