Docs: split away user image building and highlight whole disk images

The user image documentation applies to both standalone and glance
usage, but we keep it in the glance section. This change creates
a new page to talk about user images.

We also don't emphasize the difference between partition and whole
disk images enough, resulting in users trying whole disk images
with kernel/ramdisk set. Make the difference clearer.

Conflicts:
	doc/source/install/standalone.rst

Change-Id: I7185679203e0f9aa7ebe9c69971009cd59271b89
(cherry picked from commit 530ec9d0b1)

doc/source/install/configure-glance-images.rst

@@ -1,54 +1,9 @@
 .. _image-requirements:
 
-Create and add images to the Image service
+Add images to the Image service
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Bare Metal provisioning requires two sets of images: the deploy images
+#. Build or download the user images as described in :doc:`creating-images`.
-and the user images. The deploy images are used by the Bare Metal service
-to prepare the bare metal server for actual OS deployment. Whereas the
-user images are installed on the bare metal server to be used by the
-end user. Below are the steps to create the required images and add
-them to the Image service:
-
-#. Build the user images
-
-   The `disk-image-builder`_ can be used to create user images required for
-   deployment and the actual OS which the user is going to run.
-
-   .. _disk-image-builder: https://docs.openstack.org/diskimage-builder/latest/
-
-   - Install diskimage-builder package (use virtualenv, if you don't
-     want to install anything globally):
-
-     .. code-block:: console
-
-        # pip install diskimage-builder
-
-   - Build the image your users will run (Ubuntu image has been taken as
-     an example):
-
-     - Partition images
-
-       .. code-block:: console
-
-          $ disk-image-create ubuntu baremetal dhcp-all-interfaces grub2 -o my-image
-
-
-     - Whole disk images
-
-       .. code-block:: console
-
-          $ disk-image-create ubuntu vm dhcp-all-interfaces -o my-image
-
-   The partition image command creates ``my-image.qcow2``,
-   ``my-image.vmlinuz`` and ``my-image.initrd`` files. The ``grub2`` element
-   in the partition image creation command is only needed if local boot will
-   be used to deploy ``my-image.qcow2``, otherwise the images
-   ``my-image.vmlinuz`` and ``my-image.initrd`` will be used for PXE booting
-   after deploying the bare metal with ``my-image.qcow2``.
-
-   If you want to use Fedora image, replace ``ubuntu`` with ``fedora`` in the
-   chosen command.
 
 #. Add the user images to the Image service
 
@@ -56,6 +11,8 @@ them to the Image service:
    and note the image UUIDs in the Image service for each one as it is
    generated.
 
+   For *partition images*:
+
    - Add the kernel and ramdisk images to the Image service:
 
      .. code-block:: console
@@ -84,14 +41,18 @@ them to the Image service:
           kernel_id=$MY_VMLINUZ_UUID --property \
           ramdisk_id=$MY_INITRD_UUID --file my-image.qcow2
 
-   .. note:: To deploy a whole disk image, a kernel_id and a ramdisk_id
+   For *whole disk images*, skip uploading and configuring kernel and ramdisk
-             shouldn't be associated with the image. For example,
+   images completely, proceed directly to uploading the main image:
 
-             .. code-block:: console
+   .. code-block:: console
 
-                $ openstack image create my-whole-disk-image --public \
+      $ openstack image create my-whole-disk-image --public \
-                  --disk-format qcow2 --container-format bare \
+        --disk-format qcow2 --container-format bare \
-                  --file my-whole-disk-image.qcow2
+        --file my-whole-disk-image.qcow2
+
+   .. warning::
+       The kernel/initramfs pair must not be set for whole disk images,
+       otherwise they'll be mistaken for partition images.
 
 #. Build or download the deploy images
 

doc/source/install/creating-images.rst

@@ -0,0 +1,65 @@
+Create user images for the Bare Metal service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bare Metal provisioning requires two sets of images: the deploy images
+and the user images. The :ref:`deploy images <deploy-ramdisk>` are used by the
+Bare Metal service to prepare the bare metal server for actual OS deployment.
+Whereas the user images are installed on the bare metal server to be used by
+the end user. There are two types of user images:
+
+*partition images*
+    contain only the contents of the root partition. Additionally, two more
+    images are used together with them: an image with a kernel and with
+    an initramfs.
+
+    .. warning::
+        To use partition images with local boot, Grub2 must be installed on
+        them.
+
+*whole disk images*
+    contain a complete partition table with one or more partitions.
+
+    .. warning::
+        The kernel/initramfs pair must not be used with whole disk images,
+        otherwise they'll be mistaken for partition images.
+
+Building user images
+^^^^^^^^^^^^^^^^^^^^
+
+The `disk-image-builder`_ can be used to create user images required for
+deployment and the actual OS which the user is going to run.
+
+- Install diskimage-builder package (use virtualenv, if you don't
+  want to install anything globally):
+
+  .. code-block:: console
+
+     # pip install diskimage-builder
+
+- Build the image your users will run (Ubuntu image has been taken as
+  an example):
+
+  - Partition images
+
+    .. code-block:: console
+
+       $ disk-image-create ubuntu baremetal dhcp-all-interfaces grub2 -o my-image
+
+  - Whole disk images
+
+    .. code-block:: console
+
+       $ disk-image-create ubuntu vm dhcp-all-interfaces -o my-image
+
+The partition image command creates ``my-image.qcow2``,
+``my-image.vmlinuz`` and ``my-image.initrd`` files. The ``grub2`` element
+in the partition image creation command is only needed if local boot will
+be used to deploy ``my-image.qcow2``, otherwise the images
+``my-image.vmlinuz`` and ``my-image.initrd`` will be used for PXE booting
+after deploying the bare metal with ``my-image.qcow2``. For whole disk images
+only the main image is used.
+
+If you want to use Fedora image, replace ``ubuntu`` with ``fedora`` in the
+chosen command.
+
+.. _disk-image-builder: https://docs.openstack.org/diskimage-builder/latest/

doc/source/install/index.rst

@@ -15,8 +15,9 @@ It contains the following sections:
    get_started.rst
    refarch/index
    install.rst
-   configure-integration.rst
+   creating-images.rst
    deploy-ramdisk.rst
+   configure-integration.rst
    setup-drivers.rst
    enrollment.rst
    standalone.rst

doc/source/install/standalone.rst

@@ -110,7 +110,8 @@ Steps to start a deployment are pretty similar to those when using Compute:
 
     openstack baremetal port create $MAC_ADDRESS --node $NODE_UUID
 
-#. You also need to specify some fields in the node's ``instance_info``:
+#. You also need to specify image information in the node's ``instance_info``
+   (see :doc:`creating-images`):
 
    * ``image_source`` - URL of the whole disk or root partition image,
      mandatory. For :ref:`direct-deploy` only HTTP(s) links are accepted,
@@ -141,7 +142,7 @@ Steps to start a deployment are pretty similar to those when using Compute:
         md5sum *.img > checksums
 
    * ``kernel``, ``ramdisk`` - HTTP(s) or file URLs of the kernel and
-     initramfs of the target OS, only required for partition images.
+     initramfs of the target OS. Must be added **only** for partition images.
 
    For example::
 
@@ -152,6 +153,12 @@ Steps to start a deployment are pretty similar to those when using Compute:
         --instance-info ramdisk=$RAMDISK \
         --instance-info root_gb=10
 
+   With a whole disk image::
+
+    openstack baremetal node set $NODE_UUID \
+        --instance-info image_source=$IMG \
+        --instance-info image_checksum=$MD5HASH
+
 #. Validate that all parameters are correct::
 
     openstack baremetal node validate $NODE_UUID