Plugins

Storage Plugins

This section gives an outline of how to implement a plugin to integrate a third-party storage provider. For details and an example, you will need to read the code.

Note

Example code is available at: plugins/storage/volume/sample

Third party storage providers can integrate with CloudStack to provide either primary storage or secondary storage. For example, CloudStack provides plugins for Amazon Simple Storage Service (S3) or OpenStack Object Storage (Swift). The S3 plugin can be used for any object storage that supports the Amazon S3 interface.

Additional third party object storages that do not support the S3 interface can be integrated with CloudStack by writing plugin software that uses the object storage plugin framework. Several new interfaces are available so that storage providers can develop vendor-specific plugins based on well-defined contracts that can be seamlessly managed by CloudStack.

Artifacts such as Templates, ISOs and Snapshots are kept in storage which CloudStack refers to as secondary storage. To improve scalability and performance, as when a number of hosts access secondary storage concurrently, object storage can be used for secondary storage. Object storage can also provide built-in high availability capability. When using object storage, access to secondary storage data can be made available across multiple zones in a region. This is a huge benefit, as it is no longer necessary to copy Templates, Snapshots etc. across zones as would be needed in an environment using only zone-based NFS storage.

The user enables a storage plugin through the UI. A new dialog box choice is offered to select the storage provider. Depending on which provider is selected, additional input fields may appear so that the user can provide the additional details required by that provider, such as a user name and password for a third-party storage account.

Overview of How to Write a Storage Plugin

To add a third-party storage option to CloudStack, follow these general steps (explained in more detail later in this section):

Implement the following interfaces in Java:
- DataStoreDriver
- DataStoreLifecycle
- DataStoreProvider
- VMSnapshotStrategy (if you want to customize the Instance Snapshot functionality)
Hardcode your plugin’s required additional input fields into the code for the Add Secondary Storage or Add Primary Storage dialog box.
Place your .jar file in plugins/storage/volume/ or plugins/storage/image/.
Edit /client/tomcatconf/componentContext.xml.in.
Edit client/pom.xml.

Implementing DataStoreDriver

DataStoreDriver contains the code that CloudStack will use to provision the object store, when needed.

You must implement the following methods:

getTO()
getStoreTO()
createAsync()
deleteAsync()

The following methods are optional:

resize()
canCopy() is optional. If you set it to true, then you must implement copyAsync().

Implementing DataStoreLifecycle

DataStoreLifecycle contains the code to manage the storage operations for ongoing use of the storage. Several operations are needed, like create, maintenance mode, delete, etc.

You must implement the following methods:

initialize()
maintain()
cancelMaintain()
deleteDataStore()
Implement one of the attach*() methods depending on what scope you want the storage to have: attachHost(), attachCluster(), or attachZone().

Implementing DataStoreProvider

DataStoreProvider contains the main code of the data store.

You must implement the following methods:

getDatastoreLifeCycle()
getDataStoreDriver()
getTypes(). Returns one or more types of storage for which this data store provider can be used. For secondary object storage, return IMAGE, and for a Secondary Staging Store, return ImageCache.
configure(). First initialize the lifecycle implementation and the driver implementation, then call registerDriver() to register the new object store provider instance with CloudStack.
getName(). Returns the unique name of your provider; for example, this can be used to get the name to display in the UI.

The following methods are optional:

getHostListener() is optional; it’s for monitoring the status of the host.

Implementing VMSnapshotStrategy

VMSnapshotStrategy has the following methods:

takeVMSnapshot()
deleteVMSnapshot()
revertVMSnapshot()
canHandle(). For a given Instance Snapshot, tells whether this implementation of VMSnapshotStrategy can handle it.

Place the .jar File in the Right Directory

For a secondary storage plugin, place your .jar file here:

plugins/storage/image/

For a primary storage plugin, place your .jar file here:

plugins/storage/volume/

Edit Configuration Files

First, edit the following file tell CloudStack to include your .jar file. Add a line to this file to tell the CloudStack Management Server that it now has a dependency on your code:

client/pom.xml

Place some facts about your code in the following file so CloudStack can run it:

/client/tomcatconf/componentContext.xml.in

In the section “Deployment configurations of various adapters,” add this:

<bean>id=”some unique ID” class=”package name of your implementation of DataStoreProvider”</bean>

In the section “Storage Providers,” add this:

<property name=”providers”>
   <ref local=”same ID from the bean tag's id attribute”>
</property>

Minimum Required Interfaces

The classes, interfaces, and methods used by CloudStack from the Amazon Web Services (AWS) Java SDK are listed in this section. An object storage that supports the S3 interface is minimally required to support the below in order to be compatible with CloudStack.

Interface AmazonS3

http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3.html

Modifier and Type	Method and Description
Bucket	createBucket(String bucketName) Creates a new Amazon S3 bucket with the specified name in the default (US) region, Region.US_Standard.
void	deleteObject(String bucketName, String key) Deletes the specified object in the specified bucket.
ObjectMetadata	getObject(GetObjectRequest getObjectRequest, File destinationFile) Gets the object metadata for the object stored in Amazon S3 under the specified bucket and key, and saves the object contents to the specified file.
S3Object	getObject(String bucketName, String key) Gets the object stored in Amazon S3 under the specified bucket and key.
URL	generatePresignedUrl(String bucketName, String key, Date expiration, HttpMethod method) Returns a pre-signed URL for accessing an Amazon S3 resource.
void	deleteBucket(String bucketName) Deletes the specified bucket.
List<Bucket>	listBuckets() Returns a list of all Amazon S3 buckets that the authenticated sender of the request owns.
ObjectListing	listObjects(String bucketName, String prefix) Returns a list of summary information about the objects in the specified bucket.
PutObjectResult	putObject(PutObjectRequest putObjectRequest) Uploads a new object to the specified Amazon S3 bucket.
PutObjectResult	putObject(String bucketName, String key, File file) Uploads the specified file to Amazon S3 under the specified bucket and key name.
PutObjectResult	putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata) Uploads the specified input stream and object metadata to Amazon S3 under the specified bucket and key name.
void	setEndpoint(String endpoint) Overrides the default endpoint for this client.
void	setObjectAcl(String bucketName, String key, CannedAccessControlList acl) Sets the CannedAccessControlList for the specified object in Amazon S3 using one of the pre-configured CannedAccessControlLists.

Class TransferManager

http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/transfer/TransferManager.html

Modifier and Type	Method and Description
Upload	upload(PutObjectRequest putObjectRequest) Schedules a new transfer to upload data to Amazon S3.

Class PutObjectRequest

http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/PutObjectRequest.html

Modifier and Type	Method and Description
Upload	upload(PutObjectRequest putObjectRequest) Schedules a new transfer to upload data to Amazon S3.