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