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 Conf documentation for VTN Manager, please refer to:
 110 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/manager.model/apidocs/index.html
 111
 112
 113 For VTN Java API documentation, please refer to:
 114 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/apidocs/index.html
 115
 116 Once the Karaf distribution is up, install dlux and apidocs.
 117
 118 ::
 119
 120     feature:install odl-dlux-all odl-mdsal-apidocs
 121
 122 Logging In
 123 ''''''''''
 124
 125 To Log in to DLUX, after installing the application:
 126
 127 -  Open a browser and enter the login URL as
 128    `http://<OpenDaylight-IP>:8181/index.html <http://<OpenDaylight-IP>:8181/index.html>`__.
 129
 130 .. note::
 131
 132     Replace "<OpenDaylight-IP>" with the IP address of OpenDaylight
 133     based on your environment.
 134
 135 -  Login to the application with user ID and password credentials as
 136    admin.
 137
 138 .. note::
 139
 140     admin is the only default user available for DLUX in this release.
 141
 142 -  In the right hand side frame, click "Yang UI".
 143
 144 YANG documentation for VTN Manager, please refer to:
 145 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/manager.model/apidocs/index.html
 146
 147 VTN Coordinator
 148 ~~~~~~~~~~~~~~~
 149
 150 The VTN Coordinator is an external application that provides a REST
 151 interface for an user to use OpenDaylight VTN Virtualization. It
 152 interacts with the VTN Manager plugin to implement the user
 153 configuration. It is also capable of multiple OpenDaylight
 154 orchestration. It realizes VTN provisioning in OpenDaylight instances.
 155 In the OpenDaylight architecture VTN Coordinator is part of the network
 156 application, orchestration and services layer. VTN Coordinator will use
 157 the REST interface exposed by the VTN Manger to realize the virtual
 158 network using OpenDaylight. It uses OpenDaylight APIs (REST) to
 159 construct the virtual network in OpenDaylight instances. It provides
 160 REST APIs for northbound VTN applications and supports virtual networks
 161 spanning across multiple OpenDaylight by coordinating across
 162 OpenDaylight.
 163
 164 VTN Coordinator Components:
 165
 166 -  Transaction Coordinator
 167
 168 -  Unified Provider Physical Layer (UPPL)
 169
 170 -  Unified Provider Logical LAyer (UPLL)
 171
 172 -  OpenDaylight Controller Diver (ODC Driver)
 173
 174 OpenDaylight Virtual Tenant Network (VTN) API Overview
 175 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 176
 177 The VTN API module is a sub component of the VTN Coordinator and
 178 provides the northbound REST API interface for VTN applications. It
 179 consists of two subcomponents:
 180
 181 -  Web Server
 182
 183 -  VTN service Java API Library
 184
 185 .. figure:: ./images/vtn/vtn-coordinator-api-architecture.png
 186    :alt: VTN-Coordinator\_api-architechture
 187
 188    VTN-Coordinator\_api-architechture
 189
 190 Web Server
 191 ''''''''''
 192
 193 The Web Server module handles the REST APIs received from the VTN
 194 applications. It translates the REST APIs to the appropriate Java APIs.
 195
 196 The main functions of this module are:
 197
 198 -  Starts via the startup script ``catalina.sh``.
 199
 200 -  VTN Application sends HTTP request to Web server in XML or JSON
 201    format.
 202
 203 -  Creates a session and acquire a read/write lock.
 204
 205 -  Invokes the VTN Service Java API Library corresponding to the
 206    specified URI.
 207
 208 -  Returns the response to the VTN Application.
 209
 210 WebServer Class Details
 211 '''''''''''''''''''''''
 212
 213 The list below shows the classes available for Web Server module and
 214 their descriptions:
 215
 216 Init Manager
 217     It is a singleton class for executing the acquisition of
 218     configuration information from properties file, log initialization,
 219     initialization of VTN Service Java API Library. Executed by init()
 220     of VtnServiceWebAPIServlet.
 221
 222 Configuration Manager
 223     Maintains the configuration information acquired from properties
 224     file.
 225
 226 VtnServiceCommonUtil
 227     Utility class
 228
 229 VtnServiceWebUtil
 230     Utility class
 231
 232 VtnServiceWebAPIServlet
 233     Receives HTTP request from VTN Application and calls the method of
 234     corresponding VtnServiceWebAPIHandler. herits class HttpServlet, and
 235     overrides doGet(), doPut(), doDelete(), doPost().
 236
 237 VtnServiceWebAPIHandler
 238     Creates JsonObject(com.google.gson) from HTTP request, and calls
 239     method of corresponding VtnServiceWebAPIController.
 240
 241 VtnServiceWebAPIController
 242     Creates RestResource() class and calls UPLL API/UPPL API through
 243     Java API. the time of calling UPLL API/UPPL API, performs the
 244     creation/deletion of session, acquisition/release of configuration
 245     mode, acquisition/release of read lock by TC API through Java API.
 246
 247 Data Converter
 248     Converts HTTP request to JsonObject and JsonXML to JSON.
 249
 250 VTN Service Java API Library
 251 ''''''''''''''''''''''''''''
 252
 253 It provides the Java API library to communicate with the lower layer
 254 modules in the VTN Coordinator. The main functions of this library are:
 255
 256 -  Creates an IPC client session to the lower layer.
 257
 258 -  Converts the request to IPC framework format.
 259
 260 -  Invokes the lower layer API (i.e. UPPL API, UPLL API, TC API).
 261
 262 -  Returns the response from the lower layer to the web server
 263
 264 -  VTN Service Java API Library Class Details
 265
 266 Feature Overview
 267 ^^^^^^^^^^^^^^^^
 268
 269 VTN Coordinator doesn’t have Karaf features.
 270
 271 For VTN Coordinator REST API, please refer to:
 272 https://wiki.opendaylight.org/view/OpenDaylight_Virtual_Tenant_Network_%28VTN%29:VTN_Coordinator:RestApi
 273
 274 Usage Examples
 275 ~~~~~~~~~~~~~~
 276
 277 -  `L2 Network using Single
 278    Controller <https://wiki.OpenDaylight.org/view/OpenDaylight_Virtual_Tenant_Network_(VTN):VTN_Coordinator:RestApi:How_to_configure_L2_Network_with_Single_Controller>`__
 279