View source for Aperi Device Server R2 Extensibility

= Introduction =

This page provides information about extension points available when adding vendor-specific storage devices to Aperi. The sections within this page are organized as a series of HOWTOs to help you get started quickly with extending the Data server.

For example, a walk-through of the code extensions for adding the IBM Storage Virtualization Controller (SVC) to Aperi is provided. Keep in mind the following with this example: because SVC support is included in the existing Aperi code, the extensions and code separation is not as strict as when you create a device extension from scratch. There is no separate bundle for the SVC created and the specific classes do not reside in separate packages. Additionally, some SVC specific API methods and Constants are mixed in other classes.

Note: Device specific GUI extensions or additions to the database layout are not part of the device server extensibility and not covered in this article.

As with all software projects, Aperi will evolve over time. However, the content of this page is specific to its 0.2/0.3 release will evolve in response to the needs of Aperi developers. Please share any questions, comments, and concerns on the Aperi Development mailing list (https://dev.eclipse.org/mailman/listinfo/aperi-dev) or the Aperi newsgroup (http://www.eclipse.org/newsgroups/index_project.php).

= How do you extend device discovery? =

Aperi's device discovery attempts to identify SAN devices and collect the basic device data such as: vendor, machine type and serial number. It also attempts to identify the functional type of the device such as: disk array, inband storage virtualizer, and switch or fabric.

== Extension org.eclipse.aperi.discovery.discoveryProcessPlugin ==

The Interface org.eclipse.aperi.disk.discovery.DiscoveryProcessPlugin defines methods to initialize the Discovery Request and to collect the data for device discovery. The discoveryProcessPlugin Extension point takes an implementation of this interface for a specific device, all devices of the same kind, or a generic discovery implementation.

For SMI-S devices, generic implementations of the DiscoveryProcessPlugin are available in the abstract class org.eclipse.aperi.disk.discovery.ProcessPlugin and the class org.eclipse.aperi.disk.discovery.GenericDiscoveryProcessPlugin.

For an SVC device, most data is discovered by the GenericDiscoveryProcessPlugin, but some settings need correction. Therefore, the  GenericDiscoveryProcessPlugin class is extended by SVCDiscoveryProcessPlugin. This class needs to be defined as a discoveryProcessPluginextension point. 

The “impl” extension point attribute takes the device specific implementation class, for the SVC it's SVCDiscoveryProcessPlugin. The other extension point attributes are optional, although you need to set some because they define the conditions for which this plugin has to be selected for device discovery.

For the SVC the condition is that the device CIMOM provides a server profile (no_server_profile = false) and the SMIS attribute property “element_name” starts with the String “SVC”.

= How do you extend device probes? =

During a probe of a device, information about all the entities of a SAN device are collected and stored into the Aperi database repository. For SMIS-enabled devices, the SMIS class associations are traversed and the CIM objects and their relations are retrieved and persisted with database mappers.

The main building blocks for the probe process are the DiscoverProcess and the Istep.

The different DiscoverProcess and their process sequences are maintained by the IStep interface. The IStep interface maintains a list of subsequent ISteps which are processed sequentially afterwards.

The abstract class org.eclipse.aperi.DiscoverProcess represents a single step in the probe. This might reach from a complete device discovery by invoking subsequent DiscoverProcesses or basic steps such as executing a single SMIS-CIM call (for example, the AssociatorCIMQuery DiscoverProcess).

Because the DiscoverProcess implementations can be used in such different ways there are different options to extend the probe with customized DiscoverProcess classes.

== Service org.eclipse.aperi.discovery.interfaces.IDiscoverRouterService ==

To perform a special SMIS CIM-call there would be a large overhead to create a unique DiscoverProvess class. Instead, you can instantiate the  AssociatorCIMQuery with several parameters, defining the CIM query and names for the new CIMQuery-Process and the result objects. The name of this customized instance must be unique and extend the probe by registering with the IDiscoverRouterService.addProcess() method.
This registration has to be done actively during runtime, so during DiskManager service startup() the static method ProbeSVCSubsystemProcess.registerSteps() is called.

In the future for the DiscoverProcesses that need to be instantiated before registering, you can define individual Extension Points that take all required parameters and supports lazy initialization. 

== Extension org.eclipse.aperi.discovery.discoverProcess ==

The discoverProcess extension takes a discoverProcess implementation and a name for this process. Duplicate names are allowed, because additional extension attributes define which extension to choose out of several DiscoverProcess with the same name. In Aperi, the main probe DiscoverProcesses that define complete device probes are defined through this extension point.

For an SVC device, a ProbeSVCSubsystemProcess extends the ProbeGenericInBandVirtualizerProcess. Additionally, different versions of the SVC CIMOM behave in different ways, so special probe processes are required for older and newer SVC CIMOMs:
* The ProbeSVCLegacySubsystemProcess for older CIMOMs is registered with the attributes  DiscoverProcessName “collectDataFromStorageSubsystem”, the SMIS Profile “In Band Virtualization”, the Vendor “IBM” and all legacy CIMOM version strings. 
*The newer SVC CIMOMs are handled by the ProbeSVCNonLegacySubsystemProcess class, which is registered without  a CIMOM version.

The same is true for probing the Mapping and Masking data. The ProbeGenericMaskingMappingProcess is extended for SVC with the class ProbeSVCLegacyMaskingMappingProcess for old CIMOMs and the class ProbeSVCMaskingMappingProcess for newer SVC CIMOM versions.

Additional DiscoverProcesses are used that are summarized as ProbePostProcessing. There are no further CIM calls done, but the collected data is analyzed. For example, the  SVCExtentUpdatePostProcess maps the SVCs Mdisk (stored as Extents) to already probed Volumes of the SVCs backend Disk Devices.

The SVC specific probe processes are defining probe step sequences that use the SVC specific DiscoverProcesses that are registered with unique names to the IDiscoverRouterService, as described in the the previous section.

= Extent Database Mapper =


== Extension org.eclipse.aperi.common.dbAttributeMapper ==

Device Discovery and Probe are using database Mappers to persist the CIM Object attributes to the database. Device specific attribute names or the format of the values often requires special mappers.
These can be defined by implementing the interface org.eclipse.aperi.interfaces.IDBAttributeMapper or by extending an existing mapper class. For the new class a dbAttributeMapper Extension needs to be defined that includes the SMISRegistration attributes to select the new mapper class.
For the SVC device the generic mapper classes are extended but they are registered directly using the legacy MapperPackage and not through the Extension, which should be corrected in a later release.



= Extent Device Control =

In Aperi R0.2 only the Disk component provides SMI-S based Control functions while Fabric relies on the Inband-Agents and Tape has no control functions at all. Therefore only the Disk component provides fine grained extensibility.

== Extension org.eclipse.aperi.control.controller ==

The Aperi control bundle provides the controller extension point to add control functions. It is extended by an implementation of the org.eclipse.aperi.interfaces.IControl Interface, which has an empty definition. All control methods has to be defined in a Interface that extends this IControl interface. The control functionality has to be implemented in a class that implements the IController interface or extend the Controller abstract class, which contains the management functions for the control class.

== Extension org.eclipse.aperi.disk.storageConfiguration ==

To support device specific implementations of the disk control functions the Extension point storageConfiguration is defined in the disk bundle.
A device specific class must implement the org.eclipse.aperi.disk.control.IStorageConfigurationManagementPlugin interface or extend the StorageConfigurationPlugin class. The other extension attributes define for which device to use the plugin.
For the SVC a StorageConfigurationPluginSVC extends the StorageConfigurationPlugin class and is registered for the profile “SMIS_IN_BAND_VIRTUALIZATION”, the vendor “IBM”, type “SVC” and  all 1.0 and 1.1 SMIS versions. The plugin implements the method createSVCVDisks() and provides SVC specific CIMManagement classes.

== Class org.eclipse.aperi.disk.common.CIM.CIMManagement ==

The  IstorageConfigurationManagementPlugin defines methods to access CIMManagement classes that can handle access to the CIMOM in a device or CIMOM specific way. Because it is included in the storageConfiguration extension no separate extension point is defined. For SVC the HWIDMangement, VolumeManagement and MappingManagement classes are modified to fit the SVC device. So these class instances are returned by the corresponding  StorageConfigurationPluginSVC methods.

= Extent the Webservice API =

For the SVC device an additional API method createSVCVDisks() was added to the device servers webservice API. For the SVC device the method is included with the other generic disk device methods in the DiskConfigurationOperations class and the IDiskManagerService interface.
For future API extension an own OSGi Service containing the new API methods should be defined. The service has to be published as a device server webservice by defining and setting the webservice name as OSGi service attribute “org.eclipse.aperi.webservice.name”.
Depending on the added functionality it might be a good idea to extent the   IdiskManagerService interface and the DiskConfigurationOperations class and add the new methods, which will provide a complete webservice API interface to the client.