Queens openstack client does not support --block-device

[Andrea Ieri]

This bug tracker is for errors with the documentation, use the following as a template and remove or add fields as you see fit. Convert [ ] into [x] to check boxes:

- [x] This doc is inaccurate in this way:

Anchor #create-volume-from-image-and-boot-instance describes the usage of option --block-device to generate a volume from an image and boot from there. That option is not implemented in the Queens openstack client, although it does exist in the nova client.
I suggest substituting the openstack client syntax with the equivalent nova syntax.

If you have a troubleshooting or support issue, use the following resources:

 - Ask OpenStack: http://ask.openstack.org
 - The mailing list: http://lists.openstack.org
 - IRC: 'openstack' channel on Freenode

-----------------------------------
Release: 17.0.6.dev116 on 2018-09-22 00:26
SHA: 8157b16a65094035cbf0efc75e7bd6a2feee150f
Source: https://git.openstack.org/cgit/openstack/nova/tree/doc/source/user/launch-instance-from-volume.rst
URL: https://docs.openstack.org/nova/queens/user/launch-instance-from-volume.html

[Matt Riedemann (mriedem)]

The description of the --block-device parameters in #3 here:

https://docs.openstack.org/nova/latest/user/launch-instance-from-volume.html#create-volume-from-image-and-boot-instance

Are definitely wrong, since you can't use openstack client CLI to boot a server from an image and have nova create a volume. OSC only supports booting from an image or an existing volume, not creating a new root volume from a source image or volume snapshot.

Note that steps 4 and 5 are more accurate - it creates a bootable volume from an image (step 4) and then uses that to create the server (step 5).

The --block-device parameter description in step 3 should probably just reference the OSC CLI docs since those are the source of truth for that command:

https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/server.html#server-create

Alternatively, just change step 3 to be the nova boot command because that's what the --block-device parameters described there are coming from, not OSC:

https://docs.openstack.org/python-novaclient/latest/cli/nova.html#nova-boot

That was probably a regression when someone went through that document and updated the nova CLIs to OSC CLIs.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/607589

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/607589
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=16027094ebabc5cd9f2e766431f18aadeff54a40
Submitter: Zuul
Branch: master

commit 16027094ebabc5cd9f2e766431f18aadeff54a40
Author: Matt Riedemann <email address hidden>
Date: Wed Oct 3 10:27:22 2018 -0400

    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.

    Change-Id: I985b870759d6c21ef9357b04f39099c02354f135
    Closes-Bug: #1794827

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova 19.0.0.0rc1 release candidate.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/rocky
Review: https://review.opendev.org/693554

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/693554
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=6a6d0e943443a9cdd9b56aa9a93768d05e4dde0e
Submitter: Zuul
Branch: stable/rocky

commit 6a6d0e943443a9cdd9b56aa9a93768d05e4dde0e
Author: Matt Riedemann <email address hidden>
Date: Wed Oct 3 10:27:22 2018 -0400

    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.

    Change-Id: I985b870759d6c21ef9357b04f39099c02354f135
    Closes-Bug: #1794827
    (cherry picked from commit 16027094ebabc5cd9f2e766431f18aadeff54a40)

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/queens
Review: https://review.opendev.org/694357

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/694357
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=c55eff39f22bec875d7be296fef7f72585689729
Submitter: Zuul
Branch: stable/queens

commit c55eff39f22bec875d7be296fef7f72585689729
Author: Matt Riedemann <email address hidden>
Date: Wed Oct 3 10:27:22 2018 -0400

    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.

    Change-Id: I985b870759d6c21ef9357b04f39099c02354f135
    Closes-Bug: #1794827
    (cherry picked from commit 16027094ebabc5cd9f2e766431f18aadeff54a40)
    (cherry picked from commit 6a6d0e943443a9cdd9b56aa9a93768d05e4dde0e)

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: stable/pike
Review: https://review.opendev.org/694450

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/694450
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=cf73bff104b6557e74c7eb0c4d210c0b6ab4b199
Submitter: Zuul
Branch: stable/pike

commit cf73bff104b6557e74c7eb0c4d210c0b6ab4b199
Author: Matt Riedemann <email address hidden>
Date: Wed Oct 3 10:27:22 2018 -0400

    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)

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova 18.3.0 release.

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova pike-eol release.

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova queens-eol release.