Add new API to force live migration to complete

[OpenStack Infra]

https://review.openstack.org/245921
Dear bug triager. This bug was created since a commit was marked with DOCIMPACT.
Your project "openstack/nova" is set up so that we directly report the documentation bugs against it. If this needs changing, the docimpact-group option needs to be added for the project. You can ask the OpenStack infra team (#openstack-infra on freenode) for help if you need to.

commit c9091d0871948377685feca0eb2e41d8ad38228a
Author: Pawel Koniszewski <email address hidden>
Date: Mon Feb 8 08:59:52 2016 +0100

    Add new API to force live migration to complete

    This change adds manual knob to force ongoing live migration to
    complete. It is implemented as a new server-migrations API.

    DocImpact
    ApiImpact

    Implements: blueprint pause-vm-during-live-migration
    Change-Id: I034b4041414a797f65ede52db2963107f2ef7456

[Sean Dague (sdague)]

This requires microversion support, which we don't currently have. Marking as incomplete for that reason

[Sean Dague (sdague)]

This probably needs to be cleaned up to be sent over to the openstack-manuals folks

[Markus Zoeller (markus_z) (mzoeller)]

The official tag "documentation" got changed to "doc" to match it
with the bug reports which get generated by merged commits with a
"DocImpact" in the commit message.

[Markus Zoeller (markus_z) (mzoeller)]

I pinged Pawel (the change author) in IRC, to get more information here before routing the report to the manuals team.

[Pawel Koniszewski (pawel-koniszewski)]

So, this is a new feature that added new API to force live migration to complete. It can be used on a VM that is being live migrated (task state MIGRATING) and right now it is supported only when libvirt is used as a virt driver. Basically it pauses a VM, so that it does not write to memory which means that live migration will end in a finite time because of no dirty pages. Two typical use cases for this feature are:

* Live migration is stuck but you really need to move an instance to another host
* Live migration is taking long time but it's a critical case and you need to finish it ASAP

VM is automatically unpaused at the end of the process, even if the process fails. By default attached policy allows admins only to use this feature.

New API call is:
POST /servers/<instance_uuid>/migrations/<migration_id>/action
Body: {'force_complete': null}
Through CLI: nova live-migration-force-complete <instance_uuid/name> <migration_id>

Migration ID can be obtained by listing all in-progress live migrations for particular instance:
GET /servers/<instance_uuid>/migrations
Through CLI: nova server-migration-list <instance_uuid/name>

[Markus Zoeller (markus_z) (mzoeller)]

Addition:
    POST /servers/<instance_uuid>/migrations/<migration_id>/action
doesn't have a response body

[Markus Zoeller (markus_z) (mzoeller)]

@Manuals-Team:
See comments #5 + #6. Feel free to contact us if more information is needed.

[Alexandra Settle (alexandra-settle)]

Best suited: https://docs.openstack.org/admin-guide/compute-configuring-migrations.html or https://docs.openstack.org/admin-guide/compute-live-migration-usage.html

[melanie witt (melwitt)]

This is several years old and also documented at https://docs.openstack.org/nova/latest/admin/live-migration-usage.html.