Updated example usage of VTN API.

[docs.git] / manuals / user-guide / src / main / asciidoc / vtn / VTN_Overview.adoc

=== VTN Overview

OpenDaylight Virtual Tenant Network (VTN) is an application that provides multi-tenant virtual network on an SDN controller.

Conventionally, huge investment in the network systems and operating expenses are needed because the network is configured as a silo for each department and system. So, various network appliances must be installed for each tenant and those boxes cannot be shared with others. It is a heavy work to design, implement and operate the entire complex network.

The uniqueness of VTN is a logical abstraction plane. This enables the complete separation of logical plane from physical plane. Users can design and deploy any desired network without knowing the physical network topology or bandwidth restrictions.

VTN allows the users to define the network with a look and feel of conventional L2/L3 network. Once the network is designed on VTN, it will automatically be mapped into underlying physical network, and then configured on the individual switch leveraging SDN control protocol. The definition of logical plane makes it possible not only to hide the complexity of the underlying network but also to better manage network resources. It achieves reducing reconfiguration time of network services and minimizing network configuration errors.

.VTN Overview
image::vtn/VTN_Overview.jpg[VTN Overview ,width= 500]

It is implemented as two major components

* <<_vtn_manager,VTN Manager>>
* <<_vtn_coordinator,VTN Coordinator>>

==== VTN Manager
An OpenDaylight Controller Plugin that interacts with other modules to implement the components of the VTN model. It also provides a REST interface to configure VTN components in ODL controller. VTN Manager is implemented as one plugin to the OpenDaylight controller. This provides a REST interface to create/update/delete VTN components. The user command in VTN Coordinator is translated as REST API to VTN Manager by the ODC Driver component. In addition to the above mentioned role, it also provides an implementation to the Openstack L2 Network Functions API.

===== Features Overview

* *odl-vtn-manager* provides VTN Manager's JAVA API.
* *odl-vtn-manager-rest* provides VTN Manager's REST API.
* *odl-vtn-manager-neutron* provides the integration with Neutron interface.

===== REST API

VTN Manager provides REST API for virtual network functions.

Here is an example of how to create a virtual tenant network.

----
 curl --user "admin":"admin" -H "Accept: application/json" -H \
 "Content-type: application/json" -X POST \
 http://localhost:8282/controller/nb/v2/vtn/default/vtns/Tenant1 \
 -d '{"description": "My First Virtual Tenant Network"}'
----

You can check the list of all tenants by executing the following command.

----
 curl --user "admin":"admin" -H "Accept: application/json" -H \
 "Content-type: application/json" -X GET \
 http://localhost:8282/controller/nb/v2/vtn/default/vtns
----

REST API documentation for VTN Manager, please refer: https://jenkins.opendaylight.org/releng/view/vtn/job/vtn-merge-master/lastSuccessfulBuild/artifact/manager/northbound/target/site/wsdocs/rest.html

==== VTN Coordinator

The VTN Coordinator is an external application that provides a REST interface for a user to use the VTN Virtualization. It interacts with VTN Manager plugin to implement the user configuration. It is also capable of multiple controller orchestration. It realizes Virtual Tenant Network (VTN) provisioning in OpenDaylight Controllers (ODC). In the OpenDaylight architecture VTN Coordinator is part of the network application, orchestration and services layer. VTN Coordinator has been implemented as an external application to the OpenDaylight controller. This component is responsible for the VTN virtualization. VTN Coordinator will use the REST interface exposed by the VTN Manger to realize the virtual network using the OpenDaylight controller. It uses OpenDaylight APIs (REST) to construct the virtual network in ODCs. It provides REST APIs for northbound VTN applications and supports virtual networks spanning across multiple ODCs by coordinating across ODCs.

For VTN Coordinator REST API, please refer: https://wiki.opendaylight.org/view/OpenDaylight_Virtual_Tenant_Network_%28VTN%29:VTN_Coordinator:RestApi

==== Network Virtualization Function

The user first defines a VTN. Then, the user maps the VTN to a physical network, which enables communication to take place according to the VTN definition. With the VTN definition, L2 and L3 transfer functions and flow-based traffic control functions (filtering and redirect) are possible.

==== Virtual Network Construction

The following table shows the elements which make up the VTN.
In the VTN, a virtual network is constructed using virtual nodes (vBridge, vRouter) and virtual interfaces and links.
It is possible to configure a network which has L2 and L3 transfer function, by connecting the virtual intrefaces made on virtual nodes via virtual links.

[cols="2*"]
|===
|vBridge
|The logical representation of L2 switch function.

|vRouter
|The logical representation of router function.

|vTep
|The logical representation of Tunnel End Point - TEP.

|vTunnel
|The logical representation of Tunnel.

|vBypass
|The logical representation of connectivity between controlled networks.

|Virtual interface
|The representation of end point on the virtual node.

|Virtual Linkv(vLink)
|The logical representation of L1 connectivity between virtual interfaces.
|===

The following figure shows an example of a constructed virtual network. VRT is defined as the vRouter, BR1 and BR2 are defined as vBridges. interfaces of the vRouter and vBridges are connected using vLinks.

.VTN Construction
image::vtn/VTN_Construction.jpg[VTN Construction ,width= 500]


==== Mapping of Physical Network Resources

Map physical network resources to the constructed virtual network. Mapping identifies which virtual network each packet transmitted or received by an OpenFlow switch belongs to, as well as which interface in the OpenFlow switch transmits or receives that packet.
There are two mapping methods. When a packet is received from the OFS, port mapping is first searched for the corresponding mapping definition, then VLAN mapping is searched, and the packet is mapped to the relevant vBridge according to the first matching mapping.

[cols="2*"]
|===
|Port mapping
|Maps physical network resources to an interface of vBridge using Switch ID, Port ID and VLAN ID of the incoming L2 frame. Untagged frame mapping is also supported.

|VLAN mapping
|Maps physical network resources to a vBridge using VLAN ID of the incoming L2 frame.Maps physical resources of a particular switch to a vBridge using switch ID and VLAN ID of the incoming L2 frame.

|MAC mapping
|Maps physical resources to an interface of vBridge using MAC address of the incoming L2 frame(The initial contribution does not include this method).
|===

VTN can learn the terminal information from a terminal that is connected to a switch which is mapped to VTN. Further, it is possible to refer that terminal information on the VTN.

* Learning terminal information
  VTN learns the information of a terminal that belongs to VTN. It will store the MAC address and VLAN ID of the terminal in relation to the port of the switch.
* Aging of terminal information
  Terminal information, learned by the VTN, will be maintained until the packets from terminal keep flowing in VTN. If the terminal gets disconnected from the VTN, then the aging timer will start clicking and the terminal information will be maintained till timeout.

The following figure shows an example of mapping. An interface of BR1 is mapped to port GBE0/1 of OFS1 using port mapping. Packets received from GBE0/1 of OFS1 are regarded as those from the corresponding interface of BR1.
BR2 is mapped to VLAN 200 using VLAN mapping.
Packets with VLAN tag 200 received from any ports of any OFSs are regarded as those from an interface of BR2.

.VTN Mapping
image::vtn/VTN_Mapping.jpg[VTN Mapping]

==== vBridge Functions

The vBridge provides the bridge function that transfers a packet to the intended virtual port according to the destination MAC address.
The vBridge looks up the MAC address table and transmits the packet to the corresponding virtual interface when the destination MAC address has been learned. When the destination MAC address has not been learned, it transmits the packet to all virtual interfaces other than the receiving port (flooding).
MAC addresses are learned as follows.

* MAC address learning
  The vBridge learns the MAC address of the connected host. The source MAC address of each received frame is mapped to the receiving virtual interface, and this MAC address is stored in the MAC address table created on a per-vBridge basis.
* MAC address aging
  The MAC address stored in the MAC address table is retained as long as the host returns the ARP reply. After the host is disconnected, the address is retained until the aging timer times out.
To have the vBridge learn MAC addresses statically, you can register MAC addresses manually.

==== vRouter Functions

The vRouter transfers IPv4 packets between vBridges. The vRouter supports routing, ARP learning, and ARP aging functions. The following outlines the functions.

* Routing function
  When an IP address is registered with a virtual interface of the vRouter, the default routing information for that interface is registered. It is also possible to statically register routing information for a virtual interface.
* ARP learning function
  The vRouter associates a destination IP address, MAC address and a virtual interface, based on an ARP request to its host or a reply packet for an ARP request, and maintains this information in an ARP table prepared for each routing domain. The registered ARP entry is retained until the aging timer, described later, times out. The vRouter transmits an ARP request on an individual aging timer basis and deletes the associated entry from the ARP table if no reply is returned. For static ARP learning, you can register ARP entry information manually.
*DHCP relay agent function
  The vRouter also provides the DHCP relay agent function.

==== Flow Filter Functions

Flow Filter function is similar to ACL. It is possible to allow or prohibit communication with only certain kind of packets that meet a particular condition. Also, it can perform a processing called Redirection - WayPoint routing, which is different from the existing ACL.
Flow Filter can be applied to any interface of a vNode within VTN, and it is possible to the control the packets that pass interface.
The match conditions that could be specified in Flow Filter are as follows. It is also possible to specify a combination of multiple conditions.

* Source MAC address
* Destination MAC address
* MAC ether type
* VLAN Priority
* Source IP address
* Destination IP address
* DSCP
* IP Protocol
* TCP/UDP source port
* TCP/UDP destination port
* ICMP type
* ICMP code

The types of Action that can be applied on packets that match the Flow Filter conditions are given in the following table.
It is possible to make only those packets, which match a particular condition, to pass through a particular server by specifying Redirection in Action. E.g., path of flow can be changed for each packet sent from a particular terminal, depending upon the destination IP address.
VLAN priority control and DSCP marking are also supported.


[cols="2*"]
|===
| Pass
| Pass particular packets matching the specified conditions.

| Drop
| Discards particular packets matching the specified conditions.

| Redirection
| Redirects the packet to a desired virtual interface. Both Transparent Redirection (not changing MAC address) and Router Redirection (changing MAC address) are supported.
|===

The following figure shows an example of how the flow filter function works.

If there is any matching condition specified by flow filter when a packet being transferred within a virtual network goes through a virtual interface, the function evaluates the matching condition to see whether the packet matches it.
If the packet matches the condition, the function applies the matching action specified by flow filter. In the example shown in the figure, the function evaluates the matching condition at BR1 and discards the packet if it matches the condition.

.VTN FlowFilter
image::vtn/VTN_Flow_Filter.jpg[width=500]

==== Multiple SDN Controller Coordination

With the network abstractions, VTN enables to configure virtual network across multiple SDN controllers. This provides highly scalable network system.

VTN can be created on each SDN controller. If users would like to manage those multiple VTNs with one policy, those VTNs can be integrated to a single VTN.

As a use case, this feature is deployed to multi data center environment. Even if those data centers are geographically separated and controlled with different controllers, a single policy virtual network can be realized with VTN.

Also, one can easily add a new SDN Controller to an existing VTN or delete a particular SDN Controller from VTN.

In addition to this, one can define a VTN which covers both OpenFlow network and Overlay network at the same time.

Flow Filter, which is set on the VTN, will be automatically applied on the newly added SDN Controller.

==== Coordination between OpenFlow Network and L2/L3 Network

It is possible to configure VTN on an environment where there is mix of L2/L3 switches as well. L2/L3 switch will be shown on VTN as vBypass. Flow Filter or policing cannot be configured for a vBypass. However, it is possible to treat it as a virtual node inside VTN.

==== Virtual Tenant Network (VTN) API

VTN provides Web APIs. They are implemented by REST architecture and provide the access to resources within VTN that are identified by URI.
User can perform the operations like GET/PUT/POST/DELETE against the virtual network resources (e.g. vBridge or vRouter) by sending a message to VTN through HTTPS communication in XML or JSON format.

.VTN API
image::vtn/VTN_API.jpg[VTN API]

===== Function Outline

VTN provides following operations for various network resources.

[cols="5*"]
|===
| Resources
| GET
| POST
| PUT
| DELETE

| VTN
| Yes
| Yes
| Yes
| Yes

| vBridge
| Yes
| Yes
| Yes
| Yes

| vRouter
| Yes
| Yes
| Yes
| Yes

| vTep
| Yes
| Yes
| Yes
| Yes

| vTunnel
| Yes
| Yes
| Yes
| Yes

| vBypass
| Yes
| Yes
| Yes
| Yes

| vLink
| Yes
| Yes
| Yes
| Yes

| Interface
| Yes
| Yes
| Yes
| Yes

| Port map
| Yes
| No
| Yes
| Yes

| Vlan map
| Yes
| Yes
| Yes
| Yes

| Flowfilter (ACL/redirect)
| Yes
| Yes
| Yes
| Yes

| Controller information
| Yes
| Yes
| Yes
| Yes

| Physical topology information
| Yes
| No
| No
| No

| Alarm information
| Yes
| No
| No
| No
|===

===== Example usage

The following is an example of the usage to construct a virtual network.

* Create VTN

----
   curl --user admin:adminpass -X POST -H 'content-type: application/json'  \
  -d '{"vtn":{"vtn_name":"VTN1"}}' http://172.1.0.1:8083/vtn-webapi/vtns.json
----
* Create Controller Information

----
   curl --user admin:adminpass -X POST -H 'content-type: application/json'  \
  -d '{"controller": {"controller_id":"CONTROLLER1","ipaddr":"172.1.0.1","type":"odc","username":"admin", \
  "password":"admin","version":"1.0"}}' http://172.1.0.1:8083/vtn-webapi/controllers.json
----
* Create vBridge under VTN

----
  curl --user admin:adminpass -X POST -H 'content-type: application/json' \
  -d '{"vbridge":{"vbr_name":"VBR1","controller_id": "CONTROLLER1","domain_id": "(DEFAULT)"}}' \
  http://172.1.0.1:8083/vtn-webapi/vtns/VTN1/vbridges.json
----
* Create the interface under vBridge

----
  curl --user admin:adminpass -X POST -H 'content-type: application/json' \
  -d '{"interface":{"if_name":"IF1"}}' http://172.1.0.1:8083/vtn-webapi/vtns/VTN1/vbridges/VBR1/interfaces.json
----