From 775d89ed0fe539fa40b607347f8ad7557fba4624 Mon Sep 17 00:00:00 2001
From: Stephen Finucane <sfinucan@redhat.com>
Date: Mon, 10 Jun 2019 17:42:37 +0100
Subject: [PATCH] docs: Document how to revert, confirm a cold migration

This relies on the recently added 'openstack server migrate confirm' and
'openstack server migrate revert' commands.

Change-Id: I58d0a62aeeb4bb23a7ed3a8e9fe5ddb7f2dd3877
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Depends-On: I0cb6304c794bffaec785add9f7b8cf53ab28cacd
---
 doc/source/admin/migration.rst | 110 +++++++++++++++++++++------------
 1 file changed, 69 insertions(+), 41 deletions(-)

diff --git a/doc/source/admin/migration.rst b/doc/source/admin/migration.rst
index 6eebab1ad4cf..d156218d4811 100644
--- a/doc/source/admin/migration.rst
+++ b/doc/source/admin/migration.rst
@@ -4,64 +4,92 @@ Migrate instances
 
 .. note::
 
-   This documentation is about cold-migration. For live-migration usage, see
+   This documentation is about cold migration. For live migration usage, see
    :doc:`live-migration-usage`.
 
-When you want to move an instance from one compute host to another, you can use
-the :command:`openstack server migrate` command. The scheduler chooses the
-destination compute host based on its settings. This process does not assume
-that the instance has shared storage available on the target host. If you are
-using SSH tunneling, you must ensure that each node is configured with SSH key
-authentication so that the Compute service can use SSH to move disks to other
-nodes. For more information, see :ref:`cli-os-migrate-cfg-ssh`.
+When you want to move an instance from one compute host to another, you can
+migrate the instance. The migration operation, which is also known as the cold
+migration operation to distinguish it from the live migration operation,
+functions similarly to :doc:`the resize operation </user/resize>` with the main
+difference being that a cold migration does not change the flavor of the
+instance. As with resize, the scheduler chooses the destination compute host
+based on its settings. This process does not assume that the instance has shared
+storage available on the target host. If you are using SSH tunneling, you must
+ensure that each node is configured with SSH key authentication so that the
+Compute service can use SSH to move disks to other nodes. For more information,
+see :ref:`cli-os-migrate-cfg-ssh`.
 
-#. To list the VMs you want to migrate, run:
+To list the VMs you want to migrate, run:
 
-   .. code-block:: console
+.. code-block:: console
 
-      $ openstack server list
+   $ openstack server list
 
-#. Use the :command:`openstack server migrate` command.
+Once you have the name or UUID of the server you wish to migrate, migrate it
+using the :command:`openstack server migrate` command:
 
-   .. code-block:: console
+.. code-block:: console
 
-      $ openstack server migrate VM_INSTANCE
+   $ openstack server migrate SERVER
 
-#. To migrate an instance and watch the status, use this example script:
+Once an instance has successfully migrated, you can use the :command:`openstack
+server migrate confirm` command to confirm it:
 
-   .. code-block:: bash
+.. code-block:: console
 
-      #!/bin/bash
+   $ openstack server migrate confirm SERVER
 
-      # Provide usage
-      usage() {
-          echo "Usage: $0 VM_ID"
-          exit 1
-      }
+Alternatively, you can use the :command:`openstack server migrate revert`
+command to revert the migration and restore the instance to its previous host:
 
-      [[ $# -eq 0 ]] && usage
-      VM_ID=$1
+.. code-block:: console
 
-      # Show the details for the VM
-      echo "Instance details:"
-      openstack server show ${VM_ID}
+   $ openstack server migrate revert SERVER
 
-      # Migrate the VM to an alternate hypervisor
-      echo -n "Migrating instance to alternate host "
-      openstack server migrate ${VM_ID}
-      while [[ "$(openstack server show ${VM_ID} -f value -c status)" != "VERIFY_RESIZE" ]]; do
-          echo -n "."
-          sleep 2
-      done
-      openstack server resize --confirm ${VM_ID}
-      echo " instance migrated and resized."
+.. note::
 
-      # Show the details for the migrated VM
-      echo "Migrated instance details:"
-      openstack server show ${VM_ID}
+   You can configure automatic confirmation of migrations and resizes. Refer to
+   the :oslo.config:option:`resize_confirm_window` option for more information.
 
-      # Pause to allow users to examine VM details
-      read -p "Pausing, press <enter> to exit."
+
+Example
+-------
+
+To migrate an instance and watch the status, use this example script:
+
+.. code-block:: bash
+
+   #!/bin/bash
+
+   # Provide usage
+   usage() {
+       echo "Usage: $0 VM_ID"
+       exit 1
+   }
+
+   [[ $# -eq 0 ]] && usage
+   VM_ID=$1
+
+   # Show the details for the VM
+   echo "Instance details:"
+   openstack server show ${VM_ID}
+
+   # Migrate the VM to an alternate hypervisor
+   echo -n "Migrating instance to alternate host "
+   openstack server migrate ${VM_ID}
+   while [[ "$(openstack server show ${VM_ID} -f value -c status)" != "VERIFY_RESIZE" ]]; do
+       echo -n "."
+       sleep 2
+   done
+   openstack server migrate confirm ${VM_ID}
+   echo " instance migrated and resized."
+
+   # Show the details for the migrated VM
+   echo "Migrated instance details:"
+   openstack server show ${VM_ID}
+
+   # Pause to allow users to examine VM details
+   read -p "Pausing, press <enter> to exit."
 
 .. note::