From cf73bff104b6557e74c7eb0c4d210c0b6ab4b199 Mon Sep 17 00:00:00 2001
From: Matt Riedemann <mriedem.os@gmail.com>
Date: Wed, 3 Oct 2018 10:27:22 -0400
Subject: [PATCH] doc: fix and clarify --block-device usage in user docs

The docs on create a volume-backed server from the command
line were wrong in a few ways:

* The openstack server create command does not currently allow
  booting from a volume where a source image is provided and
  nova creates the volume from the image and uses that volume
  as the root disk. The nova boot command supports that, so the
  docs are updated to call out the nova boot command since that
  is the appropriate command in this case (even the syntax with
  the openstack server create --block-device was wrong).

* When creating a server from a bootable volume with the OSC CLI,
  either the --volume or --block-device options should be used
  for a single volume, but not both. The docs were using both, so
  the latter is dropped and a note is added which links to the CLI
  documentation for more details on --block-device option usage.

Conflicts:
      doc/source/user/launch-instance-from-volume.rst

NOTE(amodi): The conflict is due to not having
Ifa2e2bbb4c5f51f13d1a5832bd7dbf9f690fcad7 in Pike

Change-Id: I985b870759d6c21ef9357b04f39099c02354f135
Closes-Bug: #1794827
(cherry picked from commit 16027094ebabc5cd9f2e766431f18aadeff54a40)
(cherry picked from commit 6a6d0e943443a9cdd9b56aa9a93768d05e4dde0e)
(cherry picked from commit c55eff39f22bec875d7be296fef7f72585689729)
---
 .../user/launch-instance-from-volume.rst      | 26 +++++++++++++++----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/doc/source/user/launch-instance-from-volume.rst b/doc/source/user/launch-instance-from-volume.rst
index eacd7661dfac..a34dc5289c65 100644
--- a/doc/source/user/launch-instance-from-volume.rst
+++ b/doc/source/user/launch-instance-from-volume.rst
@@ -208,13 +208,14 @@ the volume to boot an instance.
    Note the ID of the flavor that you want to use to create a volume.
 
 #. To create a bootable volume from an image and launch an instance from
-   this volume, use the ``--block-device`` parameter.
+   this volume, use the ``--block-device`` parameter with the ``nova boot``
+   command.
 
    For example:
 
    .. code-block:: console
 
-      $ openstack server create --flavor FLAVOR --block-device \
+      $ nova boot --flavor FLAVOR --block-device \
         source=SOURCE,id=ID,dest=DEST,size=SIZE,shutdown=PRESERVE,bootindex=INDEX \
         NAME
 
@@ -250,6 +251,15 @@ the volume to boot an instance.
 
    - ``NAME``. The name for the server.
 
+   See the `nova boot`_ command documentation and :doc:`block-device-mapping`
+   for more details on these parameters.
+
+   .. note:: As of the Stein release, the ``openstack server create`` command
+      does not support creating a volume-backed server from a source image like
+      the ``nova boot`` command. The next steps will show how to create a
+      bootable volume from an image and then create a server from that boot
+      volume using the ``openstack server create`` command.
+
 #. Create a bootable volume from an image. Cinder makes a volume bootable
    when ``--image`` parameter is passed.
 
@@ -260,11 +270,14 @@ the volume to boot an instance.
 #. Create a VM from previously created bootable volume. The volume is not
    deleted when the instance is terminated.
 
+   .. note:: The example here uses the ``--volume`` option for simplicity. The
+      ``--block-device`` option could also be used for more granular control
+      over the parameters. See the `openstack server create`_ documentation for
+      details.
+
    .. code-block:: console
 
-      $ openstack server create --flavor 2 --volume VOLUME_ID \
-        --block-device source=volume,id=$VOLUME_ID,dest=volume,size=10,shutdown=preserve,bootindex=0 \
-        myInstanceFromVolume
+      $ openstack server create --flavor 2 --volume VOLUME_ID myInstanceFromVolume
       +--------------------------------------+--------------------------------+
       | Field                                | Value                          |
       +--------------------------------------+--------------------------------+
@@ -313,6 +326,9 @@ the volume to boot an instance.
       | b7d4-0fee2fe1da0c   |                 |        |      | on /dev/vda                     |
       +---------------------+-----------------+--------+------+---------------------------------+
 
+.. _nova boot: https://docs.openstack.org/python-novaclient/latest/cli/nova.html#nova-boot
+.. _openstack server create: https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/server.html#server-create
+
 .. _Attach_swap_or_ephemeral_disk_to_an_instance:
 
 Attach swap or ephemeral disk to an instance