Merge "Remove all references to DLUX"
[docs.git] / docs / developer-guide / virtual-tenant-network-(vtn).rst
1 .. _vtn-dev-guide:
2
3 Virtual Tenant Network (VTN)
4 ============================
5
6 OpenDaylight Virtual Tenant Network (VTN) Overview
7 --------------------------------------------------
8
9 OpenDaylight Virtual Tenant Network (VTN) is an application that
10 provides multi-tenant virtual network on an SDN controller.
11
12 Conventionally, huge investment in the network systems and operating
13 expenses are needed because the network is configured as a silo for each
14 department and system. Therefore various network appliances must be
15 installed for each tenant and those boxes cannot be shared with others.
16 It is a heavy work to design, implement and operate the entire complex
17 network.
18
19 The uniqueness of VTN is a logical abstraction plane. This enables the
20 complete separation of logical plane from physical plane. Users can
21 design and deploy any desired network without knowing the physical
22 network topology or bandwidth restrictions.
23
24 VTN allows the users to define the network with a look and feel of
25 conventional L2/L3 network. Once the network is designed on VTN, it will
26 automatically be mapped into underlying physical network, and then
27 configured on the individual switch leverage SDN control protocol. The
28 definition of logical plane makes it possible not only to hide the
29 complexity of the underlying network but also to better manage network
30 resources. It achieves reducing reconfiguration time of network services
31 and minimizing network configuration errors. OpenDaylight Virtual Tenant
32 Network (VTN) is an application that provides multi-tenant virtual
33 network on an SDN controller. It provides API for creating a common
34 virtual network irrespective of the physical network.
35
36 .. figure:: ./images/vtn/vtn-overview.png
37    :alt: VTN Architecture
38
39    VTN Architecture
40
41 It is implemented as two major components
42
43 -  :ref:`vtn-manager`
44
45 -  :ref:`vtn-coordinator`
46
47 .. _vtn-manager:
48
49 VTN Manager
50 ~~~~~~~~~~~
51
52 An OpenDaylight Plugin that interacts with other modules to implement
53 the components of the VTN model. It also provides a REST interface to
54 configure VTN components in OpenDaylight. VTN Manager is implemented as
55 one plugin to the OpenDaylight. This provides a REST interface to
56 create/update/delete VTN components. The user command in VTN Coordinator
57 is translated as REST API to VTN Manager by the OpenDaylight Driver
58 component. In addition to the above mentioned role, it also provides an
59 implementation to the OpenStack L2 Network Functions API.
60
61 Function Outline
62 ^^^^^^^^^^^^^^^^
63
64 The table identifies the functions and the interface used by VTN
65 Components:
66
67 +--------------------------+--------------------------+--------------------------+
68 | Component                | Interface                | Purpose                  |
69 +==========================+==========================+==========================+
70 | VTN Manager              | RESTful API              | Configure VTN            |
71 |                          |                          | Virtualization model     |
72 |                          |                          | components in            |
73 |                          |                          | OpenDaylight             |
74 +--------------------------+--------------------------+--------------------------+
75 | VTN Manager              | Neutron API              | Handle Networks API from |
76 |                          | implementation           | OpenStack (Neutron       |
77 |                          |                          | Interface)               |
78 +--------------------------+--------------------------+--------------------------+
79 | VTN Coordinator          | RESTful API              | (1) Uses the RESTful     |
80 |                          |                          | interface of VTN         |
81 |                          |                          | Manager and configures   |
82 |                          |                          | VTN Virtualization       |
83 |                          |                          | model components in      |
84 |                          |                          | OpenDaylight.            |
85 |                          |                          | (2) Handles multiple     |
86 |                          |                          | OpenDaylight             |
87 |                          |                          | orchestration.           |
88 |                          |                          | (3) Provides API to      |
89 |                          |                          | read the physical        |
90 |                          |                          | network details. See     |
91 |                          |                          | `samples <https://wiki   |
92 |                          |                          | .OpenDaylight.org/view/O |
93 |                          |                          | penDaylight_Virtual_Tena |
94 |                          |                          | nt_Network_(VTN):VTN_Coo |
95 |                          |                          | rdinator:RestApi:L2_Netw |
96 |                          |                          | ork_Example_Using_VTN_Vi |
97 |                          |                          | rtualization>`__         |
98 |                          |                          | for usage.               |
99 +--------------------------+--------------------------+--------------------------+
100
101 Feature Overview
102 ^^^^^^^^^^^^^^^^
103
104 There are three features
105
106 -  **odl-vtn-manager** provides VTN Manager’s JAVA API.
107
108 -  **odl-vtn-manager-rest** provides VTN Manager’s REST API.
109
110 -  **odl-vtn-manager-neutron** provides the integration with Neutron
111    interface.
112
113 REST Conf documentation for VTN Manager, please refer to:
114 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/manager.model/apidocs/index.html
115
116
117 For VTN Java API documentation, please refer to:
118 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/apidocs/index.html
119
120 .. _vtn-coordinator:
121
122 VTN Coordinator
123 ~~~~~~~~~~~~~~~
124
125 The VTN Coordinator is an external application that provides a REST
126 interface for an user to use OpenDaylight VTN Virtualization. It
127 interacts with the VTN Manager plugin to implement the user
128 configuration. It is also capable of multiple OpenDaylight
129 orchestration. It realizes VTN provisioning in OpenDaylight instances.
130 In the OpenDaylight architecture VTN Coordinator is part of the network
131 application, orchestration and services layer. VTN Coordinator will use
132 the REST interface exposed by the VTN Manger to realize the virtual
133 network using OpenDaylight. It uses OpenDaylight APIs (REST) to
134 construct the virtual network in OpenDaylight instances. It provides
135 REST APIs for northbound VTN applications and supports virtual networks
136 spanning across multiple OpenDaylight by coordinating across
137 OpenDaylight.
138
139 VTN Coordinator Components:
140
141 -  Transaction Coordinator
142
143 -  Unified Provider Physical Layer (UPPL)
144
145 -  Unified Provider Logical LAyer (UPLL)
146
147 -  OpenDaylight Controller Diver (ODC Driver)
148
149 OpenDaylight Virtual Tenant Network (VTN) API Overview
150 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
151
152 The VTN API module is a sub component of the VTN Coordinator and
153 provides the northbound REST API interface for VTN applications. It
154 consists of two subcomponents:
155
156 -  Web Server
157
158 -  VTN service Java API Library
159
160 .. figure:: ./images/vtn/vtn-coordinator-api-architecture.png
161    :alt: VTN-Coordinator\_api-architechture
162
163    VTN-Coordinator\_api-architechture
164
165 Web Server
166 ''''''''''
167
168 The Web Server module handles the REST APIs received from the VTN
169 applications. It translates the REST APIs to the appropriate Java APIs.
170
171 The main functions of this module are:
172
173 -  Starts via the startup script ``catalina.sh``.
174
175 -  VTN Application sends HTTP request to Web server in XML or JSON
176    format.
177
178 -  Creates a session and acquire a read/write lock.
179
180 -  Invokes the VTN Service Java API Library corresponding to the
181    specified URI.
182
183 -  Returns the response to the VTN Application.
184
185 WebServer Class Details
186 '''''''''''''''''''''''
187
188 The list below shows the classes available for Web Server module and
189 their descriptions:
190
191 Init Manager
192     It is a singleton class for executing the acquisition of
193     configuration information from properties file, log initialization,
194     initialization of VTN Service Java API Library. Executed by init()
195     of VtnServiceWebAPIServlet.
196
197 Configuration Manager
198     Maintains the configuration information acquired from properties
199     file.
200
201 VtnServiceCommonUtil
202     Utility class
203
204 VtnServiceWebUtil
205     Utility class
206
207 VtnServiceWebAPIServlet
208     Receives HTTP request from VTN Application and calls the method of
209     corresponding VtnServiceWebAPIHandler. herits class HttpServlet, and
210     overrides doGet(), doPut(), doDelete(), doPost().
211
212 VtnServiceWebAPIHandler
213     Creates JsonObject(com.google.gson) from HTTP request, and calls
214     method of corresponding VtnServiceWebAPIController.
215
216 VtnServiceWebAPIController
217     Creates RestResource() class and calls UPLL API/UPPL API through
218     Java API. the time of calling UPLL API/UPPL API, performs the
219     creation/deletion of session, acquisition/release of configuration
220     mode, acquisition/release of read lock by TC API through Java API.
221
222 Data Converter
223     Converts HTTP request to JsonObject and JsonXML to JSON.
224
225 VTN Service Java API Library
226 ''''''''''''''''''''''''''''
227
228 It provides the Java API library to communicate with the lower layer
229 modules in the VTN Coordinator. The main functions of this library are:
230
231 -  Creates an IPC client session to the lower layer.
232
233 -  Converts the request to IPC framework format.
234
235 -  Invokes the lower layer API (i.e. UPPL API, UPLL API, TC API).
236
237 -  Returns the response from the lower layer to the web server
238
239 -  VTN Service Java API Library Class Details
240
241 Feature Overview
242 ^^^^^^^^^^^^^^^^
243
244 VTN Coordinator doesn’t have Karaf features.
245
246 For VTN Coordinator REST API, please refer to:
247 https://wiki.opendaylight.org/view/OpenDaylight_Virtual_Tenant_Network_%28VTN%29:VTN_Coordinator:RestApi
248
249 Usage Examples
250 ~~~~~~~~~~~~~~
251
252 -  `L2 Network using Single
253    Controller <https://wiki.OpenDaylight.org/view/OpenDaylight_Virtual_Tenant_Network_(VTN):VTN_Coordinator:RestApi:How_to_configure_L2_Network_with_Single_Controller>`__