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 -  :ref:`vtn-manager`
  42
  43 -  :ref:`vtn-coordinator`
  44
  45 .. _vtn-manager:
  46
  47 VTN Manager
  48 ~~~~~~~~~~~
  49
  50 An OpenDaylight Plugin that interacts with other modules to implement
  51 the components of the VTN model. It also provides a REST interface to
  52 configure VTN components in OpenDaylight. VTN Manager is implemented as
  53 one plugin to the OpenDaylight. This provides a REST interface to
  54 create/update/delete VTN components. The user command in VTN Coordinator
  55 is translated as REST API to VTN Manager by the OpenDaylight Driver
  56 component. In addition to the above mentioned role, it also provides an
  57 implementation to the OpenStack L2 Network Functions API.
  58
  59 Function Outline
  60 ^^^^^^^^^^^^^^^^
  61
  62 The table identifies the functions and the interface used by VTN
  63 Components:
  64
  65 +--------------------------+--------------------------+--------------------------+
  66 | Component                | Interface                | Purpose                  |
  67 +==========================+==========================+==========================+
  68 | VTN Manager              | RESTful API              | Configure VTN            |
  69 |                          |                          | Virtualization model     |
  70 |                          |                          | components in            |
  71 |                          |                          | OpenDaylight             |
  72 +--------------------------+--------------------------+--------------------------+
  73 | VTN Manager              | Neutron API              | Handle Networks API from |
  74 |                          | implementation           | OpenStack (Neutron       |
  75 |                          |                          | Interface)               |
  76 +--------------------------+--------------------------+--------------------------+
  77 | VTN Coordinator          | RESTful API              | (1) Uses the RESTful     |
  78 |                          |                          | interface of VTN         |
  79 |                          |                          | Manager and configures   |
  80 |                          |                          | VTN Virtualization       |
  81 |                          |                          | model components in      |
  82 |                          |                          | OpenDaylight.            |
  83 |                          |                          | (2) Handles multiple     |
  84 |                          |                          | OpenDaylight             |
  85 |                          |                          | orchestration.           |
  86 |                          |                          | (3) Provides API to      |
  87 |                          |                          | read the physical        |
  88 |                          |                          | network details. See     |
  89 |                          |                          | `samples <https://wiki   |
  90 |                          |                          | .OpenDaylight.org/view/O |
  91 |                          |                          | penDaylight_Virtual_Tena |
  92 |                          |                          | nt_Network_(VTN):VTN_Coo |
  93 |                          |                          | rdinator:RestApi:L2_Netw |
  94 |                          |                          | ork_Example_Using_VTN_Vi |
  95 |                          |                          | rtualization>`__         |
  96 |                          |                          | for usage.               |
  97 +--------------------------+--------------------------+--------------------------+
  98
  99 Feature Overview
 100 ^^^^^^^^^^^^^^^^
 101
 102 There are three features
 103
 104 -  **odl-vtn-manager** provides VTN Manager’s JAVA API.
 105
 106 -  **odl-vtn-manager-rest** provides VTN Manager’s REST API.
 107
 108 -  **odl-vtn-manager-neutron** provides the integration with Neutron
 109    interface.
 110
 111 REST Conf documentation for VTN Manager, please refer to:
 112 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/manager.model/apidocs/index.html
 113
 114
 115 For VTN Java API documentation, please refer to:
 116 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/apidocs/index.html
 117
 118 Once the Karaf distribution is up, install dlux and apidocs.
 119
 120 ::
 121
 122     feature:install odl-dlux-all odl-mdsal-apidocs
 123
 124 Logging In
 125 ''''''''''
 126
 127 To Log in to DLUX, after installing the application:
 128
 129 -  Open a browser and enter the login URL as
 130    http://<OpenDaylight-IP>:8181/index.html
 131
 132 .. note::
 133
 134     Replace "<OpenDaylight-IP>" with the IP address of OpenDaylight
 135     based on your environment.
 136
 137 -  Login to the application with user ID and password credentials as
 138    admin.
 139
 140 .. note::
 141
 142     admin is the only default user available for DLUX in this release.
 143
 144 -  In the right hand side frame, click "Yang UI".
 145
 146 YANG documentation for VTN Manager, please refer to:
 147 https://nexus.opendaylight.org/content/sites/site/org.opendaylight.vtn/boron/manager.model/apidocs/index.html
 148
 149 .. _vtn-coordinator:
 150
 151 VTN Coordinator
 152 ~~~~~~~~~~~~~~~
 153
 154 The VTN Coordinator is an external application that provides a REST
 155 interface for an user to use OpenDaylight VTN Virtualization. It
 156 interacts with the VTN Manager plugin to implement the user
 157 configuration. It is also capable of multiple OpenDaylight
 158 orchestration. It realizes VTN provisioning in OpenDaylight instances.
 159 In the OpenDaylight architecture VTN Coordinator is part of the network
 160 application, orchestration and services layer. VTN Coordinator will use
 161 the REST interface exposed by the VTN Manger to realize the virtual
 162 network using OpenDaylight. It uses OpenDaylight APIs (REST) to
 163 construct the virtual network in OpenDaylight instances. It provides
 164 REST APIs for northbound VTN applications and supports virtual networks
 165 spanning across multiple OpenDaylight by coordinating across
 166 OpenDaylight.
 167
 168 VTN Coordinator Components:
 169
 170 -  Transaction Coordinator
 171
 172 -  Unified Provider Physical Layer (UPPL)
 173
 174 -  Unified Provider Logical LAyer (UPLL)
 175
 176 -  OpenDaylight Controller Diver (ODC Driver)
 177
 178 OpenDaylight Virtual Tenant Network (VTN) API Overview
 179 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 180
 181 The VTN API module is a sub component of the VTN Coordinator and
 182 provides the northbound REST API interface for VTN applications. It
 183 consists of two subcomponents:
 184
 185 -  Web Server
 186
 187 -  VTN service Java API Library
 188
 189 .. figure:: ./images/vtn/vtn-coordinator-api-architecture.png
 190    :alt: VTN-Coordinator\_api-architechture
 191
 192    VTN-Coordinator\_api-architechture
 193
 194 Web Server
 195 ''''''''''
 196
 197 The Web Server module handles the REST APIs received from the VTN
 198 applications. It translates the REST APIs to the appropriate Java APIs.
 199
 200 The main functions of this module are:
 201
 202 -  Starts via the startup script ``catalina.sh``.
 203
 204 -  VTN Application sends HTTP request to Web server in XML or JSON
 205    format.
 206
 207 -  Creates a session and acquire a read/write lock.
 208
 209 -  Invokes the VTN Service Java API Library corresponding to the
 210    specified URI.
 211
 212 -  Returns the response to the VTN Application.
 213
 214 WebServer Class Details
 215 '''''''''''''''''''''''
 216
 217 The list below shows the classes available for Web Server module and
 218 their descriptions:
 219
 220 Init Manager
 221     It is a singleton class for executing the acquisition of
 222     configuration information from properties file, log initialization,
 223     initialization of VTN Service Java API Library. Executed by init()
 224     of VtnServiceWebAPIServlet.
 225
 226 Configuration Manager
 227     Maintains the configuration information acquired from properties
 228     file.
 229
 230 VtnServiceCommonUtil
 231     Utility class
 232
 233 VtnServiceWebUtil
 234     Utility class
 235
 236 VtnServiceWebAPIServlet
 237     Receives HTTP request from VTN Application and calls the method of
 238     corresponding VtnServiceWebAPIHandler. herits class HttpServlet, and
 239     overrides doGet(), doPut(), doDelete(), doPost().
 240
 241 VtnServiceWebAPIHandler
 242     Creates JsonObject(com.google.gson) from HTTP request, and calls
 243     method of corresponding VtnServiceWebAPIController.
 244
 245 VtnServiceWebAPIController
 246     Creates RestResource() class and calls UPLL API/UPPL API through
 247     Java API. the time of calling UPLL API/UPPL API, performs the
 248     creation/deletion of session, acquisition/release of configuration
 249     mode, acquisition/release of read lock by TC API through Java API.
 250
 251 Data Converter
 252     Converts HTTP request to JsonObject and JsonXML to JSON.
 253
 254 VTN Service Java API Library
 255 ''''''''''''''''''''''''''''
 256
 257 It provides the Java API library to communicate with the lower layer
 258 modules in the VTN Coordinator. The main functions of this library are:
 259
 260 -  Creates an IPC client session to the lower layer.
 261
 262 -  Converts the request to IPC framework format.
 263
 264 -  Invokes the lower layer API (i.e. UPPL API, UPLL API, TC API).
 265
 266 -  Returns the response from the lower layer to the web server
 267
 268 -  VTN Service Java API Library Class Details
 269
 270 Feature Overview
 271 ^^^^^^^^^^^^^^^^
 272
 273 VTN Coordinator doesn’t have Karaf features.
 274
 275 For VTN Coordinator REST API, please refer to:
 276 https://wiki.opendaylight.org/view/OpenDaylight_Virtual_Tenant_Network_%28VTN%29:VTN_Coordinator:RestApi
 277
 278 Usage Examples
 279 ~~~~~~~~~~~~~~
 280
 281 -  `L2 Network using Single
 282    Controller <https://wiki.OpenDaylight.org/view/OpenDaylight_Virtual_Tenant_Network_(VTN):VTN_Coordinator:RestApi:How_to_configure_L2_Network_with_Single_Controller>`__
 283