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