Resource Adaptation Layer

The Resource Adaptation Layer (RAL) is a concept rather than an actual module. Its role is to integrate the resources offered by testbed owners in the PII platform. The instantiation of RAL is based on the accumulation of the runtime images of Resource Adaptors (RA). RAs are providing a common interface for communication towards the PTM components while towards each resource they implement the resource specific communication and configuration protocols.
RAL as a runtime concept provides mechanisms that aid resource discovery and monitoring by generating specific change events to communicate the resource status as well as any control information to PTM components.

Resource Adaptors

The testbed resources are entities that are published to be available for provisioning using resource adaptors (RA). RAs reside in the Resource Adaptation layer where they can be dynamically plugged-in as required. A Resource Adaptor is primarily characterized by a unique resource type throughout a PTM installation. This type definition is the subject to be published and made available as a testbed offering. It is actually an advertisement of the real resource that will be participating in testbed assemblies.

Apart from the resource type definition that is the static part of all the RAs, the dynamic part of the RA is instantiated as many times as the number of the specific resource type has been deployed and brought into the federation. Since the RA is deployed in the RA Layer that resides in the PTM machine, instantiation of the dynamic part of the RA requires the existence of binding information with the resource hosted or being on a different machine. In the simplest form this information can be a network address at which the RA has to send all the configuration requests using the appropriate communication protocol. Association of the dynamic part of an RA with the actual resource that is controlling is completed by the assignment of a unique Resource Identifier that is propagated throughout the PII infrastructure.

Every instance of the dynamic part of an RA implements a common interface that consists of the four CRUD operations: Create-Update-Query-Delete. All the interaction with the RAs is based on the use of these operations. Upon reception of such a command an RA should be able to translate it into the actual resource specific semantics and apply the appropriate management towards the resource, thus implementing the network agnostic behaviour needed by the PII concepts. The common interface is published by the RA as a web service available at a URL that is unique and closely related with the Resource Identifier.

Apart from the instruction interface that an RA is implementing for receiving all the configuration and provisioning requests it is also able to inject information into the core PTM engine for further processing. The PTM is providing a service for receiving notifications from the Resource Adaptation Layer. The notifications may originate either from the RAs or from the RAL Manager. Each reported event is marked by an Event Type so that the PTM can process it accordingly.
For every instance of an RA that is bound with resource, a web service interface is launched. The URL of such an interface (available to the Core PTM) is http://localhost:2000/axis/services/{RA Identifier}

RAL Implementation

The Resource Adaptation Layer is a concept that is instantiated as set of OSGi bundles deployed in an OSGi framework. More specifically,  Oscar has been selected as the OSGi framework.

Relationships among RA types

Between two resources and consequently between the corresponding RAs two kinds of associations are envisaged:

• The two resources reference each other, or
• One of the two contains the other

These two types of resource linking is determined during VCT design. During orchestration an RA can be requetsed to:

• update its configuration with a reference to the other resource for the first case
• create the other resource in the second case

In both cases the resource being instructed receives an indication of the type of the other resource to which it has to establish a relationship linking (either reference or containment according to VCT tool terminology). It is up to the developer of the RA to process the specific type association in the proper way.
If update was issued, the RA must realise the kind of configuration update it has to perform on the actual resource, e.g. configure an Asterisk with an additional extension that should be resolved into the IP address of the softphone that is actually the second resource. In case of a create request the RA must know how to install on its resource the child resource requested. It must also configure the connectivity information for the newly created resource so that its RA when launched is able to be properly bound with the new resource. A create related example can be the installation of a software package on a host OS. In such case the OS is the parent and the software package is the child.
In the resource creation case, there is a differentiation stemming from the fact that the configuration information contained in the orchestration create request may be vital to setting up the child resource or not. For example, if a virtual image has to be launched on a virtual server then the configuration of the image at least regarding its IP address and the root credentials have to be taken care of by the virtual server RA. On the other hand, configuration of a softphone is normally performed by its actual RA and not by the OS hosting it. Therefore, the first kind of resources are considered as non-self-configurable while the second one are considered as self-configurable. The difference is that the PTM modifies the create request in the case of self-configurable. More specifically, the configuration set sent by the Teagle is replaced in the request with an indication of the package name that is required to be used for the resource installation and the extracted configuration is submitted as an update to the newly launched RA. For example:

Single vs Multiple Instance Resources (or pre-existing vs dynamic resources)

Obviously, a PTM administrator offers a list of available resources according to the RAs deployed in its RAL. Some of these resources are software resources while (at least one) are hardware resources or resources for which there is no automated installation procedure that can be integrated in a RA. In this essence there is a discrimination between single and multiple instance resources:

• Single instance resources are those resources that normally cannot be installed on demand through the RAL. These can be even pre-exisitng software installations on any hardware platforms that a PTM operator is wishing to bring into the federation. For such resources there is need for implementing a RA that can handle the configuration of the resource and the possible instantiation on top of it of any children types. This RA should be instantiated through the PTM Manager interface as many times as the installation of such a resource. During the instantiaiton of the RA the PTM administrator has to define for it the binding parameters so that the RA instance can take control of the configuration of the resource using the proper information of the control interface of the resource. This kind of resource no matter how many instances of it are in operation inside the specific testbed it has to be marked as a pre-existing instance to which a unique identifier has been assigned.
• For multiple instance resource there is no such requirement, they only have to be created on a parent that has been already in the process of settign up the VCT or was available before the VCT was designed. Those resources will be assigned a unique identifier so that they can be referenced thereafter.

Commands RAs understand

Create Command

As already stated a parent resource may receive a command for creating a child resource. In case the child resource is a non-self-configurable one the configuration data passed as the argument if the create method will be in the form of:

<type_name>
 <conf_0>value0</conf_0>
 <conf_1>value1</conf_1>
 <conf_2>value2</conf_2>
</type_name>

While in the case of a self-configurable resource the configuration data will be in the form:

<install>
  <type>type_name</type>
  <package>package_name</package>
</install>

Update Command

The update command is always in the form:

 <conf_0>value0</conf_0>
 <conf_1>value1</conf_1>
 <conf_2>value2</conf_2>

Query Command

When query is invoked the configuration data that have been used as argument the RA may be:

 * <get></get>
 * <connectivity></connectivity>
 * <reference></reference>

The first regards retrieval of the ID formatted as:

<?xml version="1.0" encoding="utf-8"?>
<resource_type>
	<uuid type=”string”>resource_id</uuid>
</resource_type> 

this is usually invoked by the OE for assuring that the target ID is in proper state for reciving the next command.
The second case regards retrieval of the identifier tagged by “raid” (<raid></raid>) and it is invoked by the TeagleGW when references contained in a VLAN configuration must be resolved.

The final case is again invoked by the TeagleGW for resolving references inside type configurations. The intention is to retrieve those parameters from an RA that are meanigful in the configuration of the one that references it. E.g when an Asterisk RA is configured during orchestration with the reference of a softphone the TeagleGW resolves the process the specific reference in order to replace the identifier with a set of parameters that are meaningful to Asterisk, such as IP address and extension.

Notifications RAs sent

The RA must notify PTM depending on the events or its state. All the notifications are sent to the PTM by use of the corresponding web service that is published by the PTM towards the RAL. The only method available in this interface is the following:

notify(raID, eventType, eventData)

Index	RA Notification event type	event data	purpose
0	TYPE_AVAILABILITY	type name	notifies the PTM that the bundle of this type has been activated.
1	RA_REGISTRATION	web service URL of this RA	notifies the PTM that raID has been activated as a web service that is reachable at the specified URL
2	TYPE_ACTIVATION	type	notifies the PTM that the identifier raID should be associated with the specified type
3	RA_CONNECTIVITY	binding information	notifies the PTM that the identifier raID should be associated with the resource for which the binding information is specified. This is submitted either by the actual RA or by its parent in case a child is created on top of it.
4	TYPE_CONFIGURATION	configuration information	notifies the PTM that the resource with identifier raID has been configured with the specified parameters
5	ERROR_EVENT	error description	notifies the PTM that the resource with identifier raID has encountered an error
6	INFO_EVENT	information string	notifies the PTM that the resource with identifier raID is operating normally. This is used to clear a former error indication.

• The binding information used by the RA_CONNECTIVITY notification has the following format:

  <connectivity>
  	 <binding parameter 0>value parameter 0</binding parameter 0>
  	 …..
  	 <binding parameter n>value parameter n</binding parameter n>
  </connectivity>
  

• The configuration information used by the TYPE_CONFIGURATION notification has the following format:

  <configuration>
  	 <parameter 0>value parameter 0</parameter 0>
  	 …..
  	 <parameter n>value parameter n</parameter n>
  </configuration>
  

RAL (Oscar + other bundles)

The Oscar OSGi framework is installed as console (no-gui) application. This implies that its basic installation consists by default of the following bundles (as presented by Oscar's “ps” command):

   ID   State         Level  Name

[   0] [Active     ] [    0] System Bundle (1.0.5)

[   1] [Active     ] [    1] Shell Service (1.0.2)

[   2] [Active     ] [    1] Shell TUI (1.0.0)

[   3] [Active     ] [    1] Bundle Repository (1.1.2)

This basic installation is enhanced by the additional installation of the following bundles:

[   6] [Active     ] [    1] Servlet (1.0.0)

[   7] [Active     ] [    1] HTTP Service (1.1.2)

[   8] [Active     ] [    1] Commons-Logging (2.0.0)

[   9] [Active     ] [    1] axis-osgi (0.1.0)

These bundles allow for the publication of web services based interfaces. Finally there are two additional bundle that have been developed in the context of the project to provide the basic RAL environment:

[  10] [Active     ] [    1] ral-common

[  11] [Active     ] [    1] Resource Adapter Manager

Development and deployment of new resource adaptors

As already stated, RAs implement a common interface that is exposed as web service to the PTM for receiving requests and also consume a PTM interface for submitting notifications. Furthermore there are certain things an RA must follow during installation and activation. All these common characteristics have lead to the implementation of a  NetBeans module that offers the template of an RA to be instantiated as the development NetBeans? project for a type covering all the requirements and requiring from the RA developer only to implement the body of the RA for managing interaction with the resource.

After having installed the NetBeans? module one has to create a new project according to RATemplate.

The next step is the definition of the RA type (it should be in small letters, because the type is de-capitalised in the Teagle. Additionally one can define a number of configuration and binding parameters for the RA.

The created project can be directly built. Once the building is successful the created archive (in the dist folder under the project's folder) can be uploaded to the PTM Manager

Update can be ticked in order to indicate the replacement of an existing packages under the same type. Self-Configurable can be select if this is the case. Then pressing submit upload the archive to RAL and if no error is indicated the RA has been deployed.

Then the RA is listed in the Active Types table.

From there (in case of a single instance resource) we can decide either to create an instance for it or remove the type. Selecting create instance navigates to a page where we have to submit binding info and configuration parameters.

Submitting the form and navigating to the Active RA-IDs table we see the newly resource listed.

From there it is also possible to remove the instance. If the type is removed from the Active Types table, all the instances of the type are removed as well.

What is in the code?

For the implementation of the RA, the developer has to fill in the required methods in the created *Service.java file (see also an older how to). There are two Java Hashtable objects created in that file that are populated with binding and configuration entries that have been collected during object instantiation and update invocation respectively:

private Hashtable<String, String> m_configuration = new Hashtable<String, String>();
private Hashtable<String, String> m_binding = new Hashtable<String, String>();

by simply invoking

(m_configuration or m_binding).get(“bind_1” or “conf_1”)

we get back the appropriate parameter the use of which is up to the RA developer and resource needs.

In the case of Create request, after the placeholder for creating the child resource there is a block of code that takes care of submitting for the new RA the connectivity parameters of the parent that are common to the child. If additional ones exist the developer has to append these in the following way:

conn+="<"+newTypeBindingParams[i]+">"+“value”+"</"+newTypeBindingParams[i]+">";

before the closing tag is appended (conn += "</connectivity>";)

(It is obvious that this has to be done only for those values of the “i” index are not common between parent and child or for those that must be different than the parents.)