Merge "Enhances and updates bare metal information"

doc/admin-guide-cloud/ch_compute.xml

@@ -59,8 +59,10 @@
                     Xen, Citrix XenServer and Xen Cloud Platform (XCP)</para>
             </listitem>
             <listitem>
-                <para><link xlink:href="https://wiki.openstack.org/wiki/GeneralBareMetalProvisioningFramework">
+                <para><link
-                        Bare Metal</link> - Provisions physical hardware through pluggable sub-drivers.</para>
+                            xlink:href="https://wiki.openstack.org/wiki/Baremetal"
+                            >Bare Metal</link> - Provisions physical hardware through pluggable
+                        sub-drivers</para>
             </listitem>
         </itemizedlist>
     </section>

doc/common/section_baremetal.xml

@@ -6,21 +6,18 @@ xml:id="baremetal">
     <title>Bare Metal Driver</title>
     <para>
     </para>
-    <para>
+    <para>The baremetal driver is a hypervisor driver for OpenStack Nova
-        The baremetal driver is a hypervisor driver for OpenStack Nova
+        Compute. Within the OpenStack framework, it has the same role as the
-        Compute. Within the OpenStack framework, it has the same role
+        drivers for other hypervisors (libvirt, xen, etc), and yet it is
-        as the drivers for other hypervisors (libvirt, xen, etc), and
+        presently unique in that the hardware is not virtualized - there is no
-        yet it is presently unique in that the hardware is not
+        hypervisor between the tenants and the physical hardware. It exposes
-        virtualized - there is no hypervisor between the tenants and
+        hardware via OpenStack's API, using pluggable sub-drivers to deliver
-        the physical hardware. It exposes hardware via OpenStack's
+        machine imaging (PXE) and power control (IPMI). With this, provisioning
-        API, using pluggable sub-drivers to deliver machine imaging
+        and management of physical hardware is accomplished using common cloud
-        (PXE) and power control (IPMI).  With this, provisioning and
+        APIs and tools, such as Heat or salt-cloud. However, due to this unique
-        management of physical hardware is accomplished using common
+        situation, using the baremetal driver requires some additional
-        cloud APIs and tools, such as Heat or salt-cloud. However, due
+        preparation of its environment, the details of which are beyond the
-        to this unique situation, using the baremetal driver requires
+        scope of this guide. </para>
-        some additional preparation of its environment, the details of
-        which are beyond the scope of this guide.
-    </para>
     <note><para>
             Some OpenStack Compute features are not implemented by
             the baremetal hypervisor driver.  See the <link
@@ -44,7 +41,7 @@ reserved_host_memory_mb=0</programlisting>
         Baremetal driver.  Also, some additional steps will be
         required, such as building the baremetal deploy ramdisk.  See
         the <link
-            xlink:href="https://wiki.openstack.org/wiki/GeneralBareMetalProvisioningFramework">
+            xlink:href="https://wiki.openstack.org/wiki/Baremetal">
             main wiki page</link> for details and implementation suggestions.
     </para>
 <xi:include href="tables/nova-baremetal.xml"/>

doc/common/section_cli_install.xml

@@ -15,6 +15,13 @@
     <title>Install the OpenStack command-line clients</title>
     <para>Install the prerequisite software and the Python package for
         each OpenStack client.</para>
+    <note>
+        <para>For each command, replace
+            <replaceable>PROJECT</replaceable>
+            with the lower case name of the client to
+            install, such as <literal>nova</literal>.
+            Repeat for each client.</para>
+    </note>
     <table rules="all" width="75%">
         <caption>Prerequisite software</caption>
         <col width="15%"/>
@@ -117,13 +124,6 @@
                             the clients:
                             <screen><prompt>#</prompt> <userinput>zypper install python-<replaceable>PROJECT</replaceable>client</userinput></screen></para>
                     </formalpara>
-                    <note>
-                        <para>For each command, replace
-                                <replaceable>PROJECT</replaceable>
-                            with the lower case name of the client to
-                            install, such as <literal>nova</literal>.
-                            Repeat for each client.</para>
-                    </note>
                 </td>
             </tr>
         </tbody>

doc/common/section_nova_cli_baremetal.xml

@@ -3,28 +3,31 @@
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
   <title>Manage bare metal nodes</title>
-    <para>If you use the bare metal driver, you must create and add a
+  <para>The bare metal driver for OpenStack Compute manages provisioning of
-    network interface to a bare metal node. Then, you can launch an
+    physical hardware using common cloud APIs and tools such as Orchestration
-    instance from a bare metal image.</para>
+    (Heat). The use case for this driver is for single tenant clouds such as a
-  <para>You can list and delete bare metal nodes. When you delete a
+    high-performance computing cluster or deploying OpenStack itself.
-    node, any associated network interfaces are removed. You can list
+    Development efforts are focused on moving the driver out of the Compute code
-    and remove network interfaces that are associated with a bare
+    base in the Icehouse release. If you use the bare metal driver, you must
-    metal node.</para>
+    create and add a network interface to a bare metal node. Then, you can
-
+    launch an instance from a bare metal image.</para>
- <itemizedlist><title>Commands</title><listitem>
+  <para>You can list and delete bare metal nodes. When you delete a node, any
+    associated network interfaces are removed. You can list and remove network
+    interfaces that are associated with a bare metal node.</para>
+  <itemizedlist>
+    <title>Commands</title>
+    <listitem>
       <para><command>baremetal-interface-add</command></para>
       <para>Adds a network interface to a bare metal node.</para>
     </listitem>
     <listitem>
       <para><command>baremetal-interface-list</command></para>
-      <para>Lists network interfaces associated with a bare metal
+      <para>Lists network interfaces associated with a bare metal node.</para>
-        node.</para>
     </listitem>
     <listitem>
       <para>
         <command>baremetal-interface-remove</command></para>
-      <para>Removes a network interface from a bare metal
+      <para>Removes a network interface from a bare metal node.</para>
-        node.</para>
     </listitem>
     <listitem>
       <para>
@@ -34,8 +37,7 @@
     <listitem>
       <para>
         <command>baremetal-node-delete</command></para>
-      <para>Removes a bare metal node and any associated
+      <para>Removes a bare metal node and any associated interfaces.</para>
-        interfaces.</para>
     </listitem>
     <listitem>
       <para><command>baremetal-node-list</command></para>
@@ -44,8 +46,12 @@
     <listitem>
       <para><command>baremetal-node-show</command></para>
       <para>Shows information about a bare metal node.</para>
-    </listitem></itemizedlist>
+    </listitem>
-  <procedure><title>To manage bare metal nodes</title><step><para>Create a bare metal node:</para>
+  </itemizedlist>
+  <procedure>
+    <title>To manage bare metal nodes</title>
+    <step>
+      <para>Create a bare metal node:</para>
       <screen><prompt>$</prompt> <userinput>nova baremetal-node-create --pm_address=1.2.3.4 --pm_user=ipmi --pm_password=ipmi $(hostname -f) 1 512 10 aa:bb:cc:dd:ee:ff</userinput></screen>
       <screen><computeroutput>+------------------+-------------------+
 | Property         | Value             |
@@ -64,7 +70,8 @@
 | terminal_port    | None              |
 +------------------+-------------------+</computeroutput></screen>
     </step>
-      <step><para>Add a network interface to the node:</para>
+    <step>
+      <para>Add a network interface to the node:</para>
       <screen><prompt>$</prompt> <userinput>nova baremetal-interface-add 1 aa:bb:cc:dd:ee:ff</userinput></screen>
       <screen><computeroutput>+-------------+-------------------+
 | Property    | Value             |
@@ -75,7 +82,8 @@
 | address     | aa:bb:cc:dd:ee:ff |
 +-------------+-------------------+</computeroutput>       </screen>
     </step>
-    <step><para>Launch an instance from a bare metal image:</para>
+    <step>
+      <para>Launch an instance from a bare metal image:</para>
       <screen><prompt>$</prompt> <userinput>nova boot --image my-baremetal-image --flavor my-baremetal-flavor test</userinput>        </screen>
       <screen>+-----------------------------+--------------------------------------+
 | Property                    | Value                                |
@@ -85,10 +93,11 @@
 
 ... wait for instance to become active ...       </screen>
     </step>
-      <step><para>You can list bare metal nodes and interfaces, as follows:</para>
+    <step>
+      <para>You can list bare metal nodes and interfaces, as follows:</para>
       <screen><prompt>$</prompt> <userinput>nova baremetal-node-list</userinput></screen>
-<para>When a node is in use, its status includes the UUID of the
+      <para>When a node is in use, its status includes the UUID of the instance
-        instance that runs on it:</para>
+        that runs on it:</para>
       <screen><computeroutput>+----+--------+------+-----------+---------+-------------------
   +------+------------+-------------+-------------+---------------+
 | ID | Host   | CPUs | Memory_MB | Disk_GB | MAC Address
@@ -100,8 +109,8 @@
 +----+--------+------+-----------+---------+-------------------
   +------+------------+-------------+-------------+---------------+</computeroutput></screen>
     </step>
-
+    <step>
-<step><para>Show details for a bare metal node:</para>
+      <para>Show details for a bare metal node:</para>
       <screen><prompt>$</prompt> <userinput>nova baremetal-node-show 1</userinput>     </screen>
       <screen><computeroutput>+------------------+--------------------------------------+
 | Property         | Value                                |
@@ -119,5 +128,14 @@
 | id               | 1                                    |
 | pm_user          | ipmi                                 |
 | terminal_port    | None                                 |
-+------------------+--------------------------------------+</computeroutput></screen></step></procedure>
++------------------+--------------------------------------+</computeroutput></screen>
+    </step>
+  </procedure>
+  <note>
+    <para>Set the <parameter>--availability_zone</parameter> parameter to
+      specify which zone or node to start the server. You can separate the zone
+      from the hostname with a comma. As an example:
+      <screen><prompt>$</prompt> <userinput>nova boot --availability_zone=zone:<replaceable>host</replaceable>,<replaceable>node</replaceable></userinput></screen>
+      Specifying "host" is optional for the <parameter>--availability_zone</parameter> parameter, and "zone:,node" also works.</para>
+  </note>
 </section>

doc/config-reference/compute/section_compute-hypervisors.xml

@@ -80,7 +80,7 @@
         </listitem>
         <listitem>
             <para><link
-                    xlink:href="https://wiki.openstack.org/wiki/GeneralBareMetalProvisioningFramework"
+                    xlink:href="https://wiki.openstack.org/wiki/Baremetal"
                     > Bare Metal</link> - Not a hypervisor in the
                 traditional sense, this driver provisions physical
                 hardware through pluggable sub-drivers (for example, PXE for image

doc/user-guide-admin/ch_cli.xml

@@ -34,6 +34,8 @@
     <?hard-pagebreak?>
     <xi:include href="section_nova_cli_manage_flavors.xml"/>
     <?hard-pagebreak?>
+    <xi:include href="section_nova_specify_host.xml"/>
+    <?hard-pagebreak?>
     <xi:include href="section_keystone_cli_set_quotas.xml"/>
     <?hard-pagebreak?>
     <xi:include href="section_swift_cli_analyze_log_files.xml"/>

doc/user-guide-admin/section_nova_specify_host.xml

@@ -0,0 +1,34 @@
+<?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="specify-host-to-boot-instances-on">
+    <title>Select a specific host to boot instances on</title>
+    <para>If you have the appropriate permissions, you can select the specific host where the
+        instance will be launched. This is done using the <literal>--availability_zone
+            <replaceable>zone</replaceable>:<replaceable>host</replaceable></literal>
+        arguments to the <command>nova boot</command> command. For example:</para>
+    <para>
+        <screen><prompt>$</prompt> <userinput>nova boot --image &lt;uuid&gt; --flavor m1.tiny --key_name test --availability-zone nova:server2</userinput></screen>
+    </para>
+    <para>Starting with the Grizzly release, you can specify which roles are permitted to boot
+        an instance to a specific host with the <literal>create:forced_host</literal> setting
+        within <filename>policy.json</filename> on the desired roles. By default, only the admin
+        role has this setting enabled.</para>
+    <para>You can view the list of valid compute hosts by using the <command>nova
+        hypervisor-list </command>command, for
+        example:<screen><prompt>$</prompt> <userinput>nova hypervisor-list</userinput>
+<computeroutput>+----+---------------------+
+| ID | Hypervisor hostname |
++----+---------------------+
+| 1  | server2             |
+| 2  | server3             |
+| 3  | server4             |
++----+---------------------+</computeroutput></screen></para>
+    <note>
+        <para>The <literal>--availability_zone
+            <replaceable>zone</replaceable>:<replaceable>host</replaceable></literal>
+            flag replaced the <literal>--force_hosts</literal> scheduler hint for specifying a
+            specific host, starting with the Folsom release.</para>
+    </note>
+</section>