From bcd7e4870104f56bdc2d6a2023fb025ded2f76d7 Mon Sep 17 00:00:00 2001 From: Jessica Date: Mon, 26 Aug 2013 13:47:41 -0700 Subject: [PATCH] CLOUDSTACK-4334. Documentation for how to write an object store plugin. --- docs/en-US/Developers_Guide.xml | 1 + docs/en-US/storage-plugins.xml | 125 ++++++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 docs/en-US/storage-plugins.xml diff --git a/docs/en-US/Developers_Guide.xml b/docs/en-US/Developers_Guide.xml index 87dc8a6675a..e6fb5ce9a41 100644 --- a/docs/en-US/Developers_Guide.xml +++ b/docs/en-US/Developers_Guide.xml @@ -50,6 +50,7 @@ + diff --git a/docs/en-US/storage-plugins.xml b/docs/en-US/storage-plugins.xml new file mode 100644 index 00000000000..b7f4d22d22a --- /dev/null +++ b/docs/en-US/storage-plugins.xml @@ -0,0 +1,125 @@ + + +%BOOK_ENTITIES; +]> + + Writing a Storage Plugin + 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. + + Example code is available at: + plugins/storage/volume/sample + + + Third party storage providers can integrate with &PRODUCT; to provide + either primary storage or secondary storage. + For example, &PRODUCT; provides plugins for + Amazon Simple Storage Service (S3) or OpenStack + Object Storage (Swift). Additional third party object storages can be integrated with &PRODUCT; + 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 &PRODUCT;. + Artifacts such as templates, ISOs and snapshots are kept in storage which &PRODUCT; + 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 the provider you select, additional input fields may appear so that + you 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 &PRODUCT;, implement the following interfaces in Java: + + DataStoreDriver + DataStoreLifecycle + DataStoreProvider + In addition to implementing the interfaces, you have to 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 &PRODUCT; 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 &PRODUCT;. + 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. + +
+
+ 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 &PRODUCT; to include your .jar file. + Add a line to this file to tell the &PRODUCT; 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 &PRODUCT; 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> + +
+ +