Adds script for Admin User Guide migrating a VM to another host

Change-Id: I83122fb3e0a1ea1083fe8df0baa7a55f1b432fea

doc/user-guide-admin/roadmap.rst

@@ -18,5 +18,6 @@ including great descriptions of fields and why you set a setting
 Wishlist tasks:
 - Get examples of common tasks from real admins and add to this guide as how-to: migration of VM from one host to another, quota management, targeting launch on a particular compute node
 - Create flavor example - also refer to from Ops Guide (Anne Gentle todo)
+- Migrations examples (Anne Gentle todo)
 - Create tenant example with CLI
 - Replace all individual client commands (like keystone, nova) with openstack client commands

doc/user-guide-admin/section_cli_admin_manage_environment.xml

@@ -6,6 +6,7 @@
     <xi:include href="section_cli_nova_specify_host.xml"/>
     <?hard-pagebreak?>
     <xi:include href="../common/section_cli_nova_evacuate.xml"/>
+    <xi:include href="section_cli_nova_migrate.xml"/>
     <?hard-pagebreak?>
     <xi:include href="section_cli_nova_floating_ips.xml"/>
     <?hard-pagebreak?>

doc/user-guide-admin/section_cli_nova_host_servers_migrate.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="nova_cli_host_servers_migrate">
+    <title>Migrate all instances to another compute host</title>
+    <para>When you want to move all instances from one compute host to
+        another, you can use the <command>nova
+            host-servers-migrate</command> command. The difference
+        between this command and the <command>nova evacuate</command>
+        command is that you can specify the host when evacuating. Also
+        when evacuating, you must configure shared storage on the
+        target host so that user data is preserved on the server disk.
+        See <link xlink:href="http://docs.openstack.org/user-guide/content/nova_cli_evacuate.html">Evacuate instances</link>.</para>
+    <procedure xml:id="migrate_host">
+        <step>
+            <para>To list the host you want to migrate, run:</para>
+            <screen><prompt>$</prompt> <userinput>nova service-list</userinput></screen>
+        </step>
+        <step>
+            <para>After selecting a host from the list, run this
+                command:
+            <screen><prompt>$</prompt> <userinput>nova host-servers-migrate <replaceable>HOST_NAME</replaceable></userinput></screen></para>
+            <para>Where <replaceable>HOST_NAME</replaceable> is the
+                name of the host you want the servers to go to.</para>
+            <para>All instances are booted from a new host while preserving
+                their current configurations, including ID, name, UUID, IP
+                address, and so on.</para>
+        </step>
+    </procedure>
+</section>

doc/user-guide-admin/section_cli_nova_migrate.xml

@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns="http://docbook.org/ns/docbook"
+    xmlns:xi="http://www.w3.org/2001/XInclude"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+    xml:id="nova_cli_migrate_single">
+    <title>Migrate single instance to another compute host</title>
+    <para>When you want to move an instance from one compute host to another,
+        you can use the <command>nova migrate</command> 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.</para>
+    <procedure xml:id="migrate_single">
+        <step>
+            <para>To list the VMs you want to migrate, run:</para>
+            <screen><prompt>$</prompt> <userinput>nova list</userinput></screen>
+        </step>
+        <step>
+            <para>After selecting a VM from the list, run this command where
+                <replaceable>VM_ID</replaceable> is set to the ID in the list
+                returned in the previous step:</para>
+            <screen><prompt>$</prompt> <userinput>nova show <replaceable>VM_ID</replaceable></userinput></screen>
+        </step>
+        <step>
+            <para>Now, use the <command>nova migrate</command> command:</para>
+            <screen><prompt>$</prompt> <userinput>nova migrate <replaceable>VM_ID</replaceable></userinput></screen>
+        </step>
+        <step performance="optional">
+            <para>To migrate of an instance and watch the status, use this
+                example script:</para>
+            <programlisting language="bash">#!/bin/bash
+
+# Provide usage
+usage() {
+        echo "Usage: $0 VM_ID"
+        exit 1
+}
+
+[[ $# -eq 0 ]] &amp;&amp; usage
+
+# Migrate the VM to an alternate hypervisor
+echo -n "Migrating instance to alternate host"
+$VM_ID=$1
+nova migrate $VM_ID
+VM_OUTPUT=`nova show $VM_ID`
+VM_STATUS=`echo "$VM_OUTPUT" | grep status | awk '{print $4}'`
+while [[ "$VM_STATUS" != "VERIFY_RESIZE" ]]; do
+    echo -n "."
+    sleep 2
+    VM_OUTPUT=`nova show $VM_ID`
+    VM_STATUS=`echo "$VM_OUTPUT" | grep status | awk '{print $4}'`
+done
+nova resize-confirm $VM_ID
+echo " instance migrated and resized."
+echo;
+
+# Show the details for the VM
+echo "Updated instance details:"
+nova show $VM_ID
+
+# Pause to allow users to examine VM details
+read -p "Pausing, press &lt;enter&gt; to exit."</programlisting>
+            <note>
+                <para>If you see this error, it means you are either trying the
+                    command with the wrong credentials, such as a non-admin
+                    user, or the <filename>policy.json</filename> file prevents
+                    migration for your user.
+                    <screen><computeroutput>ERROR (Forbidden): Policy doesn't allow compute_extension:admin_actions:migrate to be performed. (HTTP 403)</computeroutput></screen></para>
+            </note>
+            <para>The instance is booted from a new host, but preserves its
+                configuration including its ID, name, any metadata, IP address,
+                and other properties.</para>
+        </step>
+    </procedure>
+</section>