Bug 1285925 - [Docs] [Beta] [REST API] Document freezing/thawing the file-systems of a VM
[Docs] [Beta] [REST API] Document freezing/thawing the file-systems of a VM
Status: CLOSED CURRENTRELEASE
Product: Red Hat Enterprise Virtualization Manager
Classification: Red Hat
Component: Documentation (Show other bugs)
3.6.0
Unspecified Unspecified
unspecified Severity unspecified
: ovirt-3.6.4
: 3.6.0
Assigned To: Dayle Parker
Andrew Burden
:
Depends On: 1253562
Blocks:
  Show dependency treegraph
 
Reported: 2015-11-26 20:10 EST by Lucy Bopf
Modified: 2016-03-09 18:17 EST (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2016-03-09 18:17:37 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: Docs
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Lucy Bopf 2015-11-26 20:10:43 EST
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-23 19:48:11 EST
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-08 19:51:04 EST
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 18:17:37 EST
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

Note You need to log in before you can comment on or make changes to this bug.