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

@@ -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
+When you want to move an instance from one compute host to another, you can
-the :command:`openstack server migrate` command. The scheduler chooses the
+migrate the instance. The migration operation, which is also known as the cold
-destination compute host based on its settings. This process does not assume
+migration operation to distinguish it from the live migration operation,
-that the instance has shared storage available on the target host. If you are
+functions similarly to :doc:`the resize operation </user/resize>` with the main
-using SSH tunneling, you must ensure that each node is configured with SSH key
+difference being that a cold migration does not change the flavor of the
-authentication so that the Compute service can use SSH to move disks to other
+instance. As with resize, the scheduler chooses the destination compute host
-nodes. For more information, see :ref:`cli-os-migrate-cfg-ssh`.
+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
+Alternatively, you can use the :command:`openstack server migrate revert`
-      usage() {
+command to revert the migration and restore the instance to its previous host:
-          echo "Usage: $0 VM_ID"
-          exit 1
-      }
 
-      [[ $# -eq 0 ]] && usage
+.. code-block:: console
-      VM_ID=$1
 
-      # Show the details for the VM
+   $ openstack server migrate revert SERVER
-      echo "Instance details:"
-      openstack server show ${VM_ID}
 
-      # Migrate the VM to an alternate hypervisor
+.. note::
-      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."
 
-      # Show the details for the migrated VM
+   You can configure automatic confirmation of migrations and resizes. Refer to
-      echo "Migrated instance details:"
+   the :oslo.config:option:`resize_confirm_window` option for more information.
-      openstack server show ${VM_ID}
 
-      # 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::