Bug 1285925

Summary: [Docs] [Beta] [REST API] Document freezing/thawing the file-systems of a VM
Product: Red Hat Enterprise Virtualization Manager Reporter: Lucy Bopf <lbopf>
Component: DocumentationAssignee: Dayle Parker <dayleparker>
Status: CLOSED CURRENTRELEASE QA Contact: Andrew Burden <aburden>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 3.6.0CC: gklein, lsurette, rbalakri, yeylon, ykaul, ylavi
Target Milestone: ovirt-3.6.4   
Target Release: 3.6.0   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2016-03-09 23:17:37 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: Docs RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:
Bug Depends On: 1253562    
Bug Blocks:    

Description Lucy Bopf 2015-11-27 01:10:43 UTC
RHEV 3.6 supports adding OpenStack Cinder as an external provider. Cinder uses Ceph as its storage back end. Taking a live snapshot of a virtual machine with a Ceph/Cinder disk requires some additional steps.

Daniel Erez explains in bug 1253562:

"[W]e should add documentation for a couple of complementary features that are exposed only through the rest-api: freeze/thaw the file-systems of the VM using qemu guest agent.

During a live snapshot of a VM with Cinder disks, we must freeze filesystems on the guest OS before we take a Ceph snapshot (to ensure a consistent snapshot), and we must thaw back the guest filesystems after the snapshot was finished.

This all done automatically by the engine. However, we've exposed these actions (freeze/thaw) to the rest-api to allow manual invocation by the user (e.g. might be needed in case of a failure in thaw, in which the user can try to manually execute the thaw operation again; without it, the VM would stay unresponsive).

So, it would be helpful to add the following two examples:

1. Freeze the filesystems of the VM using qemu guest agent.

POST /api/vms/{vm:id}/freezefilesystems
Accept: application/xml
Content-Type: application/xml

<action>
</action>

2. Thaw the filesystems of the VM using qemu guest agent.

POST /api/vms/{vm:id}/thawfilesystems
Accept: application/xml
Content-Type: application/xml

<action>
</action>"

Comment 1 Lucy Bopf 2016-02-24 00:48:11 UTC
Assigning to Dayle for review.

Dayle, a quick note that this bug was originally describing a single use case (for Cinder disks), but this feature has a more general application in taking live snapshots for any running virtual machine, so the documentation for this feature should not be limited to just this use case.

Comment 2 Dayle Parker 2016-03-09 00:51:04 UTC
Added 2 new topics to the Virtual Machines -> Actions section:

* freezing virtual machine filesystems
* thawing virtual machine filesystems

I decided to keep the topic more generic about live snapshots, as Lucy suggested in the bug (https://bugzilla.redhat.com/show_bug.cgi?id=1285925#c1) as the Cinder/Ceph instructions seem to still apply to the notes here. I've also added a link to the Snapshots section of the VMM Guide.

I've switched the reviewer to Andrew Burden as he helped me out in the beginning with this bug and is already quite familiar with it.

Please let me know if it needs corrections or I've missed something.
Thanks for reviewing!

Comment 4 Andrew Burden 2016-03-09 23:17:37 UTC
This content has passed QA and is now published on the Customer Portal as part of the Red Hat Enterprise Virtualization 3.6 Documentation suite. 

REST API Guide:
Manually Freezing Virtual Machine Filesystem:
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.6/html/REST_API_Guide/sect-Actions.html#Freeze_Virtual_Machine_Filesystems_Action

Manually Thawing Virtual Machine Filesystem:
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.6/html/REST_API_Guide/sect-Actions.html#Thaw_Virtual_Machine_Filesystems_Action

Admonitions have been added to the following topics to alert users of these additional steps for taking snapshots of virtual machines if the virtual disk is on an OpenStack Volume (Cinder) disk:
Virtual Machine Snapshots Sub-collection:
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.6/html/REST_API_Guide/sect-Sub-Collections1.html#sect-Snapshots_Sub-Collection

And in the Virtual Machine Management Guide:
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.6/html/Virtual_Machine_Management_Guide/sect-Snapshots.html#Creating_a_snapshot_of_a_virtual_machine