You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ra...@apache.org on 2013/12/22 11:05:17 UTC
git commit: CLOUDSTACK-4877
Updated Branches:
refs/heads/4.3 59a23ef4f -> fe90c8f74
CLOUDSTACK-4877
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/fe90c8f7
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/fe90c8f7
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/fe90c8f7
Branch: refs/heads/4.3
Commit: fe90c8f748a4cbbf32d29fb8ef705982ad317f60
Parents: 59a23ef
Author: radhikap <ra...@citrix.com>
Authored: Sun Dec 22 15:34:48 2013 +0530
Committer: radhikap <ra...@citrix.com>
Committed: Sun Dec 22 15:34:48 2013 +0530
----------------------------------------------------------------------
en-US/images/SnapshotButton.png | Bin 0 -> 967 bytes
en-US/storage-plugins.xml | 214 +++++++++++++++++++++++++++++-----
en-US/vm-snapshots.xml | 19 ++-
en-US/working-with-snapshots.xml | 34 ++++--
4 files changed, 216 insertions(+), 51 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/fe90c8f7/en-US/images/SnapshotButton.png
----------------------------------------------------------------------
diff --git a/en-US/images/SnapshotButton.png b/en-US/images/SnapshotButton.png
new file mode 100644
index 0000000..5217740
Binary files /dev/null and b/en-US/images/SnapshotButton.png differ
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/fe90c8f7/en-US/storage-plugins.xml
----------------------------------------------------------------------
diff --git a/en-US/storage-plugins.xml b/en-US/storage-plugins.xml
index e6612c1..e92cd4d 100644
--- a/en-US/storage-plugins.xml
+++ b/en-US/storage-plugins.xml
@@ -3,25 +3,6 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
-
-<!-- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
<chapter id="storage-plugins">
<title>Writing a Storage Plugin</title>
<para>This section gives an outline of how to implement a plugin
@@ -36,7 +17,10 @@
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;
+ Object Storage (Swift). The S3 plugin can be used for any object storage
+ that supports the Amazon S3 interface.</para>
+ <para>Additional third party object storages that
+ do not support the S3 interface 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
@@ -51,24 +35,29 @@
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
+ 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.
</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
+ <para>To add a third-party storage option to &PRODUCT;, follow these general steps (explained in more detail
+ later in this section):</para>
+ <orderedlist>
+ <listitem><para>Iimplement the following interfaces in Java:</para>
+ <itemizedlist>
+ <listitem><para>DataStoreDriver</para></listitem>
+ <listitem><para>DataStoreLifecycle</para></listitem>
+ <listitem><para>DataStoreProvider</para></listitem>
+ <listitem><para>VMSnapshotStrategy (if you want to customize the VM snapshot functionality)</para></listitem>
+ </itemizedlist></listitem>
+ <listitem><para>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>
+ </orderedlist>
</section>
<section id="datastoredriver">
<title>Implementing DataStoreDriver</title>
@@ -118,6 +107,17 @@
<listitem><para>getHostListener() is optional; it's for monitoring the status of the host.</para></listitem>
</itemizedlist>
</section>
+ <section id="implement-vmsnapshotstrategy">
+ <title>Implementing VMSnapshotStrategy</title>
+ <para>VMSnapshotStrategy has the following methods:</para>
+ <itemizedlist>
+ <listitem><para>takeVMSnapshot()</para></listitem>
+ <listitem><para>deleteVMSnapshot()</para></listitem>
+ <listitem><para>revertVMSnapshot()</para></listitem>
+ <listitem><para>canHandle(). For a given VM snapshot,
+ tells whether this implementation of VMSnapshotStrategy can handle it.</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>
@@ -138,7 +138,157 @@
<programlisting><property name=”providers”>
<ref local=”same ID from the bean tag's id attribute”>
</property></programlisting>
-
- </section>
-
+ </section>
+ <section>
+ <title>Minimum Required Interfaces</title>
+ <para>The classes, interfaces, and methods used by &PRODUCT; 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 &PRODUCT;.</para>
+ <section>
+ <title>Interface AmazonS3</title>
+ <para><ulink url="http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3.html">http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/AmazonS3.html</ulink></para>
+ <informaltable>
+ <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ <colspec colwidth="1.0*" colname="1" colnum="1"/>
+ <colspec colwidth="3.35*" colname="2" colnum="2"/>
+ <thead>
+ <row>
+ <entry><para>Modifier and Type</para></entry>
+ <entry><para>Method and Description</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Bucket</para></entry>
+ <entry><para>createBucket(String bucketName)</para>
+ <para>Creates a new Amazon S3 bucket with the specified name in the default (US) region, Region.US_Standard.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>void</para></entry>
+ <entry><para>deleteObject(String bucketName, String key)</para>
+ <para>Deletes the specified object in the specified bucket.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>ObjectMetadata</para></entry>
+ <entry><para>getObject(GetObjectRequest getObjectRequest, File destinationFile)</para>
+ <para>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.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>S3Object</para></entry>
+ <entry><para>getObject(String bucketName, String key)</para>
+ <para>Gets the object stored in Amazon S3 under the specified bucket and key.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>URL</para></entry>
+ <entry><para>generatePresignedUrl(String bucketName, String key, Date expiration, HttpMethod method)</para>
+ <para>Returns a pre-signed URL for accessing an Amazon S3 resource.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>void</para></entry>
+ <entry><para>deleteBucket(String bucketName)</para>
+ <para>Deletes the specified bucket.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>List<Bucket></para></entry>
+ <entry><para>listBuckets()</para>
+ <para>Returns a list of all Amazon S3 buckets that the authenticated sender of the request owns.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>ObjectListing</para></entry>
+ <entry><para>listObjects(String bucketName, String prefix)</para>
+ <para>Returns a list of summary information about the objects in the specified bucket.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>PutObjectResult</para></entry>
+ <entry><para>putObject(PutObjectRequest putObjectRequest)</para>
+ <para>Uploads a new object to the specified Amazon S3 bucket.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>PutObjectResult</para></entry>
+ <entry><para>putObject(String bucketName, String key, File file)</para>
+ <para>Uploads the specified file to Amazon S3 under the specified bucket and key name.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>PutObjectResult</para></entry>
+ <entry><para>putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata)</para>
+ <para>Uploads the specified input stream and object metadata to Amazon S3 under the specified bucket and key name.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>void</para></entry>
+ <entry><para>setEndpoint(String endpoint)</para>
+ <para>Overrides the default endpoint for this client.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><para>void</para></entry>
+ <entry><para>setObjectAcl(String bucketName, String key, CannedAccessControlList acl)</para>
+ <para>Sets the CannedAccessControlList for the specified object in Amazon S3 using one of the pre-configured CannedAccessControlLists.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+ <section>
+ <title>Class TransferManager</title>
+ <para><ulink url="http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/transfer/TransferManager.html">http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/transfer/TransferManager.html</ulink></para>
+ <informaltable>
+ <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ <colspec colwidth="1.0*" colname="1" colnum="1"/>
+ <colspec colwidth="3.35*" colname="2" colnum="2"/>
+ <thead>
+ <row>
+ <entry><para>Modifier and Type</para></entry>
+ <entry><para>Method and Description</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Upload</para></entry>
+ <entry><para>upload(PutObjectRequest putObjectRequest)</para>
+ <para>Schedules a new transfer to upload data to Amazon S3.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+ <section>
+ <title>Class PutObjectRequest</title>
+ <para><ulink url="http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/PutObjectRequest.html">http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/model/PutObjectRequest.html</ulink></para>
+ <informaltable>
+ <tgroup cols="2" align="left" colsep="1" rowsep="1">
+ <colspec colwidth="1.0*" colname="1" colnum="1"/>
+ <colspec colwidth="3.35*" colname="2" colnum="2"/>
+ <thead>
+ <row>
+ <entry><para>Modifier and Type</para></entry>
+ <entry><para>Method and Description</para></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>Upload</para></entry>
+ <entry><para>upload(PutObjectRequest putObjectRequest)</para>
+ <para>Schedules a new transfer to upload data to Amazon S3.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+</section>
</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/fe90c8f7/en-US/vm-snapshots.xml
----------------------------------------------------------------------
diff --git a/en-US/vm-snapshots.xml b/en-US/vm-snapshots.xml
index 0708ba8..07cb5b5 100644
--- a/en-US/vm-snapshots.xml
+++ b/en-US/vm-snapshots.xml
@@ -25,7 +25,7 @@
<title>Virtual Machine Snapshots</title>
<para>(Supported on VMware and XenServer)</para>
<para>In addition to the existing &PRODUCT; ability to snapshot individual VM
- volumes, you can now take a VM snapshot to preserve all the VM's data volumes as well as
+ volumes, you can take a VM snapshot to preserve all the VM's data volumes as well as
(optionally) its CPU/memory state. This is useful for quick restore of a VM. For example, you
can snapshot a VM, then make changes such as software upgrades. If anything goes wrong, simply
restore the VM to its previous state using the previously saved VM snapshot. </para>
@@ -62,14 +62,6 @@
snapshot.</para>
</listitem>
<listitem>
- <para>You can not specify the "quiesce" option on the &PRODUCT;
- side when taking a VM snapshot. This option is provided by the underlying
- snapshot facility so that you can choose whether to quiesce the file system on a
- running virtual machine before taking the snapshot. The quiesce option is
- passed along from the user's choice on the hypervisor side,
- through the underlying API, and up to &PRODUCT;.</para>
- </listitem>
- <listitem>
<para>You should use only &PRODUCT; to create VM snapshots on hosts managed by
&PRODUCT;. Any snapshots that you make directly on the hypervisor will not be tracked in
&PRODUCT;.</para>
@@ -122,7 +114,7 @@
<listitem>
<para>Click the Take VM Snapshot button. <inlinemediaobject>
<imageobject>
- <imagedata fileref="./images/VMSnapshotButton.png" format="PNG"/>
+ <imagedata fileref="./images/SnapshotButton.png" format="PNG"/>
</imageobject>
</inlinemediaobject></para>
<note>
@@ -141,6 +133,13 @@
don't check this box, then only the current state of the VM disk is saved. Checking this
box makes the snapshot take longer.</para>
</listitem>
+ <listitem><para>Quiesce VM: check this box if you want to quiesce the file system on the VM
+ before taking the snapshot. Not supported on XenServer when used with &PRODUCT;-provided primary storage.</para>
+ <para>When this option is used with &PRODUCT;-provided primary storage,
+ the quiesce operation is performed by the underlying hypervisor (VMware is supported).
+ When used with another primary storage vendor's plugin, the quiesce operation is provided according
+ to the vendor's implementation.
+ </para></listitem>
<listitem>
<para>Click OK.</para>
</listitem>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/fe90c8f7/en-US/working-with-snapshots.xml
----------------------------------------------------------------------
diff --git a/en-US/working-with-snapshots.xml b/en-US/working-with-snapshots.xml
index 2d8cada..fef59cd 100644
--- a/en-US/working-with-snapshots.xml
+++ b/en-US/working-with-snapshots.xml
@@ -22,16 +22,32 @@
under the License.
-->
<section id="working-with-snapshots">
- <title>Working with Snapshots</title>
- <para>(Supported for the following hypervisors: <emphasis role="bold">XenServer</emphasis>, <emphasis role="bold">VMware vSphere</emphasis>, and <emphasis role="bold">KVM</emphasis>)</para>
- <para>&PRODUCT; supports snapshots of disk volumes. Snapshots are a point-in-time capture of virtual machine disks. Memory and CPU states are not captured. <!-- If you are using the Oracle VM hypervisor, you can not take snapshots, since OVM does not support them. --></para>
- <para>Snapshots may be taken for volumes, including both root and data disks. The administrator places a limit on the number of stored snapshots per user. Users can create new volumes from the snapshot for recovery of particular files and they can create templates from snapshots to boot from a restored disk.</para>
+ <title>Working with Volume Snapshots</title>
+ <para>(Supported for the following hypervisors: <emphasis role="bold">XenServer</emphasis>,
+ <emphasis role="bold">VMware vSphere</emphasis>, and <emphasis role="bold"
+ >KVM</emphasis>)</para>
+ <para>&PRODUCT; supports snapshots of disk volumes. Snapshots are a point-in-time capture of virtual machine disks. Memory and CPU states are not captured. If you are using the Oracle VM hypervisor, you can not take snapshots, since OVM does not support them.</para>
+ <para>Snapshots may be taken for volumes, including both root and data disks (except when the Oracle VM hypervisor is used, which does not support snapshots). The administrator places a limit on the number of stored snapshots per user. Users can create new volumes from the snapshot for recovery of particular files and they can create templates from snapshots to boot from a restored disk.</para>
<para>Users can create snapshots manually or by setting up automatic recurring snapshot policies. Users can also create disk volumes from snapshots, which may be attached to a VM like any other disk volume. Snapshots of both root disks and data disks are supported. However, &PRODUCT; does not currently support booting a VM from a recovered root disk. A disk recovered from snapshot of a root disk is treated as a regular data disk; the data on recovered disk can be accessed by attaching the disk to a VM.</para>
<para>A completed snapshot is copied from primary storage to secondary storage, where it is stored until deleted or purged by newer snapshot.</para>
- <xi:include href="automatic-snapshot-creation-retention.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="incremental-snapshots-backup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="volume-status.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="snapshot-restore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <section id="how-to-volume-snapshot">
+ <title>How to Snapshot a Volume</title>
+ <orderedlist>
+ <listitem><para>Log in to the &PRODUCT; UI as a user or administrator.</para></listitem>
+ <listitem><para>In the left navigation bar, click Storage.</para></listitem>
+ <listitem><para>In Select View, be sure Volumes is selected.</para></listitem>
+ <listitem><para>Click the name of the volume you want to snapshot.</para></listitem>
+ <listitem><para>Click the Snapshot button. <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="./images/SnapshotButton.png" format="PNG"/>
+ </imageobject>
+ </inlinemediaobject></para></listitem>
+ </orderedlist>
+ </section>
+ <xi:include href="automatic-snapshot-creation-retention.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="incremental-snapshots-backup.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="volume-status.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="snapshot-restore.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="snapshot-throttling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="snapshot-performance-vmware.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="snapshot-performance-vmware.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</section>