Updated Branches: refs/heads/4.2-forward 9a6f2de70 -> ecbd9ed93
CLOUDSTACK-4334. Documentation for how to write an object store plugin. Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/ecbd9ed9 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/ecbd9ed9 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/ecbd9ed9 Branch: refs/heads/4.2-forward Commit: ecbd9ed93d71284c9764c191fd94c5f9cf63dd6d Parents: 9a6f2de Author: Jessica <jessica.tomec...@citrix.com> Authored: Mon Aug 26 13:47:41 2013 -0700 Committer: Jessica <jessica.tomec...@citrix.com> Committed: Mon Aug 26 13:49:42 2013 -0700 ---------------------------------------------------------------------- docs/en-US/Developers_Guide.xml | 1 + docs/en-US/storage-plugins.xml | 125 +++++++++++++++++++++++++++++++++++ 2 files changed, 126 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack/blob/ecbd9ed9/docs/en-US/Developers_Guide.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/Developers_Guide.xml b/docs/en-US/Developers_Guide.xml index 87dc8a6..e6fb5ce 100644 --- a/docs/en-US/Developers_Guide.xml +++ b/docs/en-US/Developers_Guide.xml @@ -50,6 +50,7 @@ <xi:include href="whats-new.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="api-calls.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="working-with-usage-data.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> + <xi:include href="storage-plugins.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="working-with-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> <xi:include href="event-types.xml" xmlns:xi="http://www.w3.org/2001/XInclude"; /> http://git-wip-us.apache.org/repos/asf/cloudstack/blob/ecbd9ed9/docs/en-US/storage-plugins.xml ---------------------------------------------------------------------- diff --git a/docs/en-US/storage-plugins.xml b/docs/en-US/storage-plugins.xml new file mode 100644 index 0000000..b7f4d22 --- /dev/null +++ b/docs/en-US/storage-plugins.xml @@ -0,0 +1,125 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file:///C:/Program%20Files%20(x86)/Publican/DocBook_DTD/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> +<chapter id="storage-plugins"> + <title>Writing a Storage Plugin</title> + <para>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.</para> + <note> + <para>Example code is available at: + plugins/storage/volume/sample</para> + </note> + <para/> + <para>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;.</para> + <para>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.</para> + <para>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. + </para> + <section id="storage-plugin-steps"> + <title>Overview of How to Write a Storage Plugin</title> + <para>To add a third-party storage option to &PRODUCT;, implement the following interfaces in Java:</para> + <itemizedlist> + <listitem><para>DataStoreDriver</para></listitem> + <listitem><para>DataStoreLifecycle</para></listitem> + <listitem><para>DataStoreProvider</para></listitem> + <listitem><para>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.</para></listitem> + <listitem><para>Place your .jar file in plugins/storage/volume/ or plugins/storage/image/.</para></listitem> + <listitem><para>Edit /client/tomcatconf/componentContext.xml.in.</para></listitem> + <listitem><para>Edit client/pom.xml.</para></listitem> + </itemizedlist> + </section> + <section id="datastoredriver"> + <title>Implementing DataStoreDriver</title> + <para>DataStoreDriver contains the code that &PRODUCT; will use to provision the object store, when needed.</para> + <para>You must implement the following methods:</para> + <itemizedlist> + <listitem><para>getTO()</para></listitem> + <listitem><para>getStoreTO()</para></listitem> + <listitem><para>createAsync()</para></listitem> + <listitem><para>deleteAsync()</para></listitem> + </itemizedlist> + <para>The following methods are optional:</para> + <itemizedlist> + <listitem><para>resize()</para></listitem> + <listitem><para>canCopy() is optional. If you set it to true, then you must implement copyAsync().</para></listitem> + </itemizedlist> + </section> + <section id="datastorelifecycle"> + <title>Implementing DataStoreLifecycle</title> + <para>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.</para> + <para>You must implement the following methods:</para> + <itemizedlist> + <listitem><para>initialize()</para></listitem> + <listitem><para>maintain()</para></listitem> + <listitem><para>cancelMaintain()</para></listitem> + <listitem><para>deleteDataStore()</para></listitem> + <listitem><para>Implement one of the attach*() methods depending on what scope you want the storage to have: attachHost(), attachCluster(), or attachZone().</para></listitem> + </itemizedlist> + </section> + <section id="datastoreprovider"> + <title>Implementing DataStoreProvider</title> + <para>DataStoreProvider contains the main code of the data store.</para> + <para>You must implement the following methods:</para> + <itemizedlist> + <listitem><para>getDatastoreLifeCycle()</para></listitem> + <listitem><para>getDataStoreDriver()</para></listitem> + <listitem><para>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.</para></listitem> + <listitem><para>configure(). First initialize the lifecycle implementation and the driver implementation, + then call registerDriver() to register the new object store provider instance with &PRODUCT;.</para></listitem> + <listitem><para>getName(). Returns the unique name of your provider; for example, + this can be used to get the name to display in the UI.</para></listitem> + </itemizedlist> + <para>The following methods are optional:</para> + <itemizedlist> + <listitem><para>getHostListener() is optional; it's for monitoring the status of the host.</para></listitem> + </itemizedlist> + </section> + <section id="storage-plugin-code-location"> + <title>Place the .jar File in the Right Directory</title> + <para>For a secondary storage plugin, place your .jar file here:</para> + <programlisting>plugins/storage/image/</programlisting> + <para>For a primary storage plugin, place your .jar file here:</para> + <programlisting>plugins/storage/volume/</programlisting> + </section> + <section id="storage-plugin-componentcontext-xml"> + <title>Edit Configuration Files</title> + <para>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:</para> + <programlisting>client/pom.xml</programlisting> + <para>Place some facts about your code in the following file so &PRODUCT; can run it:</para> + <programlisting>/client/tomcatconf/componentContext.xml.in</programlisting> + <para>In the section âDeployment configurations of various adapters,â add this:</para> + <programlisting><bean>id=âsome unique IDâ class=âpackage name of your implementation of DataStoreProviderâ</bean></programlisting> + <para>In the section âStorage Providers,â add this:</para> + <programlisting><property name=âprovidersâ> + <ref local=âsame ID from the bean tag's id attributeâ> +</property></programlisting> + + </section> + +</chapter>
