cloudstack-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [40/46] git commit: updated refs/heads/internallb to b7709b8
Date Tue, 16 Apr 2013 18:34:45 GMT
CLOUDSTACK-1561. Docs. Add new feature VM Snapshots.


Branch: refs/heads/internallb
Commit: 50b4c9cbdde70e040126a7cc2538937820fbd02d
Parents: 3f9ee40
Author: Jessica Tomechak <>
Authored: Mon Apr 15 23:11:31 2013 -0700
Committer: Jessica Tomechak <>
Committed: Mon Apr 15 23:14:11 2013 -0700

 docs/en-US/images/VMSnapshotButton.png |  Bin 0 -> 967 bytes
 docs/en-US/images/revert-vm.png        |  Bin 0 -> 860 bytes
 docs/en-US/virtual-machines.xml        |    1 +
 docs/en-US/vm-snapshots.xml            |  146 +++++++++++++++++++++++++++
 4 files changed, 147 insertions(+), 0 deletions(-)
diff --git a/docs/en-US/images/VMSnapshotButton.png b/docs/en-US/images/VMSnapshotButton.png
new file mode 100644
index 0000000..5217740
Binary files /dev/null and b/docs/en-US/images/VMSnapshotButton.png differ
diff --git a/docs/en-US/images/revert-vm.png b/docs/en-US/images/revert-vm.png
new file mode 100644
index 0000000..04655dc
Binary files /dev/null and b/docs/en-US/images/revert-vm.png differ
diff --git a/docs/en-US/virtual-machines.xml b/docs/en-US/virtual-machines.xml
index 7c74932..20018da 100644
--- a/docs/en-US/virtual-machines.xml
+++ b/docs/en-US/virtual-machines.xml
@@ -26,6 +26,7 @@
   <xi:include href="creating-vms.xml" xmlns:xi=""/>
   <xi:include href="accessing-vms.xml" xmlns:xi=""/>
   <xi:include href="stopping-and-starting-vms.xml" xmlns:xi=""/>
+  <xi:include href="vm-snapshots.xml" xmlns:xi=""/>
   <xi:include href="changing-vm-name-os-group.xml" xmlns:xi=""/>
   <xi:include href="changing-service-offering-for-vm.xml" xmlns:xi=""/>
   <xi:include href="manual-live-migration.xml" xmlns:xi=""/>
diff --git a/docs/en-US/vm-snapshots.xml b/docs/en-US/vm-snapshots.xml
new file mode 100644
index 0000000..8d4bcf9
--- /dev/null
+++ b/docs/en-US/vm-snapshots.xml
@@ -0,0 +1,146 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" ""
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+<!-- 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
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+<section id="vm-snapshots">
+  <title>Virtual Machine Snapshots for VMware</title>
+  <para>(VMware hosts only)
+    In addition to the existing &PRODUCT; ability to snapshot VM volumes,
+    you can now take a VM snapshot to preserve all of the VM's state and data.
+    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>
+  <para>The snapshot is created using the VMware native snapshot facility. The VM snapshot
+    includes not only the data volumes, but optionally also whether the VM is running or
+    turned off (CPU state) and the memory contents. The snapshot is stored in &PRODUCT;'s
+    primary storage.</para>      
+  <para>VM snapshots can have a parent/child relationship.
+    Each successive snapshot of the same VM is the child of the snapshot that came before
+    Each time you take an additional snapshot of the same VM, it saves only the differences
+    between the current state of the VM and the state stored in the most recent previous
+    The previous snapshot becomes a parent, and the new snapshot is its child.
+    It is possible to create a long chain of these parent/child snapshots,
+    which amount to a "redo" record leading from the current state of the VM back to the

+    original.</para>
+  <para>If you need more information about VM snapshots, check out the VMware documentation
+    and the VMware Knowledge Base, especially
+    <ulink url=";externalId=1015180">Understanding
virtual machine snapshots</ulink>.</para>
+  <section id="vm-snapshot-restrictions">
+    <title>Limitations on VM Snapshots</title>
+    <itemizedlist>
+      <listitem><para>If a VM has some stored snapshots, you can't attach new
volume to the VM
+        or delete any existing volumes.
+        If you change the volumes on the VM, it would become impossible to restore the VM
+        which was created with the previous volume structure.</para></listitem>
+      <listitem><para>VM snapshots which include both data volumes and memory
can't be kept if you change the VM's
+        service offering. Any existing VM snapshots of this type will be discarded.</para></listitem>
+      <listitem>
+        <para>You can't make a VM snapshot at the same time as you are taking a volume
+          snapshot.</para>
+      </listitem>
+      <listitem>
+        <para>The "quiesce" option is not supported. This option is provided by the
+          VMware snapshot facility so that you can choose whether to quiesce the file system
+          on a running virtual machine before taking the snapshot. In &PRODUCT;, the
quiesce option is always
+          set to false; the file system is not quiesced before taking a snapshot of a running
+        </para>
+      </listitem>
+      <listitem><para>You should use only &PRODUCT; to create VM snapshots
on VMware hosts managed by &PRODUCT;.
+        Any snapshots that you make directly on vSphere will not be tracked in &PRODUCT;.</para></listitem>
+    </itemizedlist>
+  </section>
+  <section id="vm-snapshot-configure">
+    <title>Configuring VM Snapshots</title>
+    <para>The cloud administrator can use global configuration variables to control
the behavior of VM snapshots.
+      To set these variables, go through the Global Settings are of the UI.</para>
+    <informaltable>
+      <tgroup cols="2" align="left" colsep="1" rowsep="1">
+        <thead>
+          <row>
+            <entry><para>Configuration Setting Name</para></entry>
+            <entry><para>Description</para></entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry><para>vmsnapshots.max</para></entry>
+            <entry><para>The maximum number of VM snapshots that can be saved
for any given virtual machine in the cloud.
+              The total possible number of VM snapshots in the cloud is (number of VMs) *
+              If the number of snapshots for any VM ever hits the maximum, the older ones
are removed
+              by the snapshot expunge job.
+            </para></entry>
+          </row>
+          <row>
+            <entry><para>vmsnapshot.create.wait</para></entry>
+            <entry><para>Number of seconds to wait for a snapshot job to succeed
before declaring failure and issuing an error.</para></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </section>
+  <section id="vm-snapshot-usage">
+    <title>Using VM Snapshots</title>
+    <para>To create a VM snapshot using the &PRODUCT; UI:</para>
+    <orderedlist>
+      <listitem><para>Log in to the &PRODUCT; UI as a user or administrator.</para></listitem>
+      <listitem><para>Click Instances.</para></listitem>
+      <listitem><para>Click the name of the VM you want to snapshot.</para></listitem>
+      <listitem><para>Click the Take VM Snapshot button.
+        <inlinemediaobject>
+          <imageobject>
+            <imagedata fileref="./images/VMSnapshotButton.png" format="PNG"/>
+          </imageobject>
+        </inlinemediaobject></para>
+        <note><para>If a snapshot is already in progress, then clicking this
button will have no effect.</para></note><para/>
+      </listitem>
+      <listitem><para>Provide a name and description. These will be displayed
in the VM Snapshots list.</para></listitem>
+      <listitem><para>(For running VMs only) If you want to include the VM's
memory in the snapshot, click the
+        Memory checkbox. This saves the CPU and memory state of the virtual machine. If you
+        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>Click OK.</para></listitem>
+    </orderedlist>
+    <para>To delete a snapshot or restore a VM to the state saved in a particular snapshot:</para>
+    <orderedlist>
+      <listitem><para>Navigate to the VM as described in the earlier steps.</para></listitem>
+      <listitem><para>Click View VM Snapshots.</para></listitem>
+      <listitem><para>In the list of snapshots, click the name of the snapshot
you want to work with.</para></listitem>
+      <listitem><para>Depending on what you want to do:</para>
+        <para>To delete the snapshot, click the Delete button.
+          <inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="./images/delete-button.png" format="PNG"/>
+            </imageobject>
+          </inlinemediaobject></para>
+        <para>To revert to the snapshot, click the Revert button.
+          <inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="./images/revert-vm.png" format="PNG"/>
+            </imageobject>
+          </inlinemediaobject></para>
+      </listitem>
+    </orderedlist>
+    <note><para>VM snapshots are deleted automatically when a VM is destroyed.
+      You don't have to manually delete the snapshots in this case.</para></note>
+  </section>

View raw message