VEP Administration

Virtual Execution Platform Installation and Setup Guide

Introduction

Contrail's VEP software is used to connect a provider's IaaS resource with Contrail Cloud Federation. The tool provides a communication interface between the provider and the federation. It also allows a service provider's system administrator the capability of allotting a part of computational resources for participation in the cloud federation. It also allows the administrators the capability of configuring the numerous elements of their resources which are essential for supporting proper SLA administration by the federation. This page will help in proper installation and management of VEP software. VEP software supports OpenNebula 2.2 currently. Support for version 3.0 and higher will be provided very soon.

Installation

Use the official Contrail package for installing all the software. You can also download the source code and install manually. The source code is available at OW2 Forge. You will require ANT 1.8.0 or higher setup on your system. Assuming the VEP source code is downloaded under vep-gui/ below are ANT commands and results:

  • vep-gui$ ant run : it compiles and runs the VEP program
  • vep-gui$ ant jar : this compiles the code and generates an executable jar file under the vep-gui/dist/ folder.

To execute the jar, make sure its executable bit is set, doing so enables you to directly click on the file in a windowing environment and execute using the JRE of your choice. The jar can also be executed from the command line

  • vep-gui/dist$ java -jar VEPController.jar --vep-properties <arg> --log-properties <arg>

You can specify the path of system and logger configuration files. If no command line argument is provided during start-up then the default values are used instead.

Initial Configuration

shot-initial.png-settings.png

This is how the VEP software GUI looks like when started for the very first time. Notice all orange status icons near the bottom. It signifies that the software was not even able to connect to its local database. Most likely cause of this is non-existence of it and/or missing configuration file. This is easy to fix: just go to Edit->Settings from the top menu. The second image above shows the settings menu that would open up. You can override the default values contained in some of the fields.

Settings Dialog Fields

  • OpenNebula Front-End Settings
    • Machine IP -> enter the IP address of the physical machine where OpenNebula's front-end xml-rpc service is running.
    • XML-RPC Port -> enter the port number of the OpenNebula's xml-rpc service
    • OpenNebula Admin -> enter the username of the OpenNebula's administrator account
    • Password -> enter the password of the OpenNebula's administrator account.
    • Contrail Cluster ID -> this is the OpenNebula's internal cluster ID assigned to the cluster "Contrail". If no such cluster exist or if you are not sure just leave this field empty. VEP software will populate this automatically.
  • Database Settings
    • Which database back end to use? -> select your choice (mysql is preferred)
    • Mysql Server IP -> If you chose mysql option then provide the mysql server IP here
    • Port -> if you chose mysql option then provide the mysql server's Port value here
    • Mysql DB username -> if you chose mysql option then provide the mysql db username here
    • Password -> if you chose mysql option then provide the mysql user's password here
    • Database File -> if you chose sqlite option then you must specify the DB file to use as database here. Note: a DB file does not exist initially, you can browse the directory using the select button; in the file name selection dialog just specify the name and the VEP software will create the database file with that name automatically. 

If you have chosen mysql backened option, please refer to Setting the mysql DB for VEP page for detailed instructions on setting up the database properly.

  • Log Settings
    • Log File -> You must specify the logfile name where VEP software will output log messages, use the select button to browse the file system and specify the file-name for the VEP log. If the file does not exist, the software will create one automatically.
    • Max Log Size (KBytes) -> Specify the maximum log file size, if the file grows beyond the specified limit, the VEP software splits the log file automatically.
  • REST KeyStore
    • Java Keystore FIle -> select the JKS file using the file selector. This keystore must contain the server certificate necessary for providing REST services over SSL. You can use portecle to create and manage your keystore. Another tool that you may find useful is Java Keytool. It is necessary that the server's certificate is generated by a trusted CA and the CA's certificate is included in the system's Java trust store. For more details please consult Managing Java Trust Store and Key Stores page.
    • Keystore Password -> provide the password for the selected keystore file.
    • Key password -> provide the password for the server key included in the selected JKS file.

After providing all the details, click Save and the settings are saved into the VEP configuration file at the specified (or default) location for future use. Next time you run the software, the parameters are loaded from the saved configuration automatically. If you are running the software for the very first time it is advisable to close the software are start again after you have saved the configuration parameters.

Initial Execution

Upon properly setting the system configuration and restarting the software, the VEP software checks for the database schema validity. If the database schema does not exist or is corrupted, the software prompts the user for her permission to reinitialize the software's internal database. 

shot-initial-2.png

If permission is granted, the software drops all existing tables (if any) and properly creates all required tables in the internal database. If the permission is not granted, this process is canceled and the software's db handling modules are disabled.

The software services interface allows a system administrator to start and stop several services. These include -

  • the REST server
  • OpenNebula XML-RPC thread
  • set the desired log level
  • and add/modify local administrators' account.

Each of these tasks require elevated access rights and therefore if not already authenticated, an end user will be prompted to provide her admin credentials (username/password). The system knows if the database was re-initialized and hence local administrator table will be empty. In that case it prompts the user to create the initial VEP administrator account. An initial federation administrator account is also created so that federation components can use this account in performing operations that require administrator rights.

The two pictures shown below demonstrates the mentioned process.

shot-initial-3.png-shot-auth.png

Once the initial account setup is complete, the user must use this information to authenticate herself when prompted by the software. Upon successful authentication, VEP software completes the task.

REST API

VEP has a well documented and full featured REST interface that application developers can use to communicate and interface their modules with VEP. All necessary details are included in the API Document.

Working with VEP

Now that you have successfully installed and configured VEP software, let us explore all the things that can be done with the software. We will look into how you can manage and configure your initial datacenter in VEP. We will explore how you as an administrator can manage individual physical host with VEP and control which hosts participate in the larger federation. We will also look into enabling and disabling VEP's REST interface.

Setting Up Your Datacenter

VEP provides SLA support to higher layer federation modules. It is necessary for VEP software to know accurately about your physical datacenter layout details including clusters and racks that make up a particular datacenter. Although you may not provide the entire resource layout to VEP, but it is suggested to include at least those components (clusters, racks) of the datacenter to which participating (federated) physical hosts are housed/connected to. Without a proper mapping-chain (datacenter > cluster > rack > host), you will not be able to add the desired physical host for federation use. Next we will see how you can add datacenter, cluster, rack details in VEP.

Configuring Datacenter

db-1.pngdb-2.png-db-3.png

You will require administrator privileges to modify the VEP's internal database. The sequence of pictures above describe the process of adding a datacenter in the internal database. Go to the DB Management tab of the GUI and from the drop-down menu select datacenter management option. If you have not been authenticated previously, the software will prompt you for your admin credentials (username, password). Once authenticated, the datacenter form is displayed which the user can use to provide the details about her datacenter. Make sure that the correct country is selected as this parameter is used as the physical location of the datacenter.

Once all necessary details have been entered, press Add button to save the data. If there are multiple datacenters to be added, the same process can be repeated for each datacenter.

Configuring Cluster