Bug 1389313

Summary: [DOC] Document that libvirt refuses to abort post-copy migrations
Product: Red Hat Enterprise Linux 7 Reporter: Milan Zamazal <mzamazal>
Component: libvirtAssignee: Jiri Denemark <jdenemar>
Status: CLOSED ERRATA QA Contact: Lili Zhu <lizhu>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 7.3CC: dyuan, jdenemar, rbalakri, xuzhang, zpeng
Target Milestone: rc   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: libvirt-3.2.0-1.el7 Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2017-08-01 17:19:14 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Milan Zamazal 2016-10-27 12:41:21 UTC
libvirt refuses to abort migrations in post-copy mode. However, this features is not properly documented in libvirt API reference documentation. virDomainMigrateStartPostCopy just mentions:

"On the other hand once the guest is running on the destination host, the migration can no longer be rolled back because none of the hosts has complete state. If this happens, libvirt will leave the domain paused on both hosts with VIR_DOMAIN_PAUSED_POSTCOPY_FAILED reason."

This is ambiguous and suggests that the migration might actually be aborted with a libvirt call and leave the VM in an inconsistent state. And virDomainAbortJob documentation doesn't mention anything about that at all.

It should be clearly documented that virDomainAbortJob won't abort a migration job in the post-copy mode (and returns with failure on such an attempt) and thus it's safe to call it regardless of the migration phase.

Comment 2 Jiri Denemark 2017-03-31 18:46:04 UTC
Sent upstream for review: https://www.redhat.com/archives/libvir-list/2017-March/msg01702.html

Comment 3 Jiri Denemark 2017-03-31 19:51:03 UTC
Pushed upstream as

commit 9e8164d2f9ee74e81aa558879f762712ec0c8ea1
Refs: v3.2.0-rc2-4-g9e8164d2f
Author:     Jiri Denemark <jdenemar>
AuthorDate: Fri Mar 31 20:41:39 2017 +0200
Commit:     Jiri Denemark <jdenemar>
CommitDate: Fri Mar 31 20:41:39 2017 +0200

    Document virDomainAbortJob behavior for post-copy migration

    https://bugzilla.redhat.com/show_bug.cgi?id=1389313

    Signed-off-by: Jiri Denemark <jdenemar>

Comment 5 Lili Zhu 2017-06-09 06:37:02 UTC
The downstream doc /usr/share/doc/libvirt-docs-3.2.0/html/html/libvirt-libvirt-domain.html has been updated.
However, the upstream doc https://libvirt.org/html/libvirt-libvirt-domain.html
has not been updated.

Would you help to check it?

Comment 6 Jiri Denemark 2017-06-09 07:38:51 UTC
Hmm, looks like the automatic docs updater on libvirt.org is broken. I'll check with DV.

Comment 7 Lili Zhu 2017-06-12 07:37:46 UTC
As in http://libvirt.org/html/libvirt-libvirt-domain.html#virDomainAbortJob

The document has been updated as 
Requests that the current background job be aborted at the soonest opportunity. In case the job is a migration in a post-copy mode, virDomainAbortJob will report an error (see virDomainMigrateStartPostCopy for more details).


And also in http://libvirt.org/html/libvirt-libvirt-domain.html#virDomainMigrateStartPostCopy

Post-copy migration is guaranteed to converge since each page is transferred at most once no matter how fast it changes. On the other hand once the guest is running on the destination host, the migration can no longer be rolled back because none of the hosts has complete state. If this happens, libvirt will leave the domain paused on both hosts with VIR_DOMAIN_PAUSED_POSTCOPY_FAILED reason. It's up to the upper layer to decide what to do in such case. Because of this, libvirt will refuse to cancel post-copy migration via virDomainAbortJob.

As the documentation has been updated, hence, mark the bug as verified.

Comment 8 errata-xmlrpc 2017-08-01 17:19:14 UTC
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHEA-2017:1846

Comment 9 errata-xmlrpc 2017-08-01 23:59:00 UTC
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHEA-2017:1846