Make force_migrate not replace existing node

Previous to this, if once force-migrated a VM, the previous_node value
would be updated to the current node, which is likely never what an
administrator would want. Change this functionality so that the previous
node value is not changed, and update the documentation to reflect this.

client-cli/pvc.py

@@ -563,7 +563,7 @@ def vm_move(domain, target_node, selector):
 )
 @click.option(
     '-f', '--force', 'force_migrate', is_flag=True, default=False,
-    help='Force migrate an already migrated VM.'
+    help='Force migrate an already migrated VM; does not replace an existing previous node value.'
 )
 def vm_migrate(domain, target_node, selector, force_migrate):
     """

client-common/vm.py

@@ -444,6 +444,10 @@ def migrate_vm(zk_conn, domain, target_node, selector, force_migrate, is_cli=Fal
             common.stopZKConnection(zk_conn)
             return False, 'ERROR: VM "{}" is already running on node "{}".'.format(domain, current_node)
 
+    # Don't overwrite an existing last_node when using force_migrate
+    if last_node and force_migrate:
+        current_node = last_node
+
     zkhandler.writedata(zk_conn, {
         '/domains/{}/state'.format(dom_uuid): 'migrate',
         '/domains/{}/node'.format(dom_uuid): target_node,

docs/manuals/api.md

@@ -249,7 +249,7 @@ If `selector` is specified, the automatic node determination will use `selector`
 
 Attempting to `migrate` an already-migrated VM will return a failure.
 
-If `flag_force` is specified, migrate the VM even if it has already been migrated. The previous node value will be replaced with the current node; e.g. if VM `test` was on `pvchv1`, then `migrate`ed to `pvchv2`, then `flag_force` `migrate`ed to `pvchv3`, the `previous_node` would then be `pvchv2`. This can be repeated indefinitely. Note however that `move` is almost always better and more consistent than repeated `flag_force` `migrate` actions.
+If `flag_force` is specified, migrate the VM even if it has already been migrated. The previous node value will not be replaced; e.g. if VM `test` was on `pvchv1`, then `migrate`ed to `pvchv2`, then `flag_force` `migrate`ed to `pvchv3`, the `previous_node` would still be `pvchv1`. This can be repeated indefinitely.
 
 #### `/api/v1/vm/<vm>/unmigrate`
  * Methods: `POST`