From 0919ea6390e24ee359106ef76b922ec5a4e7a013 Mon Sep 17 00:00:00 2001 From: "Qiao, Liyong" <liyong.qiao@intel.com> Date: Wed, 22 Nov 2017 10:51:19 +0800 Subject: [PATCH] Api-guide: Add Block Device Mapping Added some descriptions and example about block device mapping in api-guide, this will help the API user to better understand how to provide block device mapping information in server request body. Change-Id: I5a85d7f190f7cda160e1e13805d356a2d4303bf0 --- api-guide/source/server_concepts.rst | 47 +++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/api-guide/source/server_concepts.rst b/api-guide/source/server_concepts.rst index 637e8a15db1c..03a5f0ee5d7a 100644 --- a/api-guide/source/server_concepts.rst +++ b/api-guide/source/server_concepts.rst @@ -690,7 +690,52 @@ limit. Block Device Mapping ~~~~~~~~~~~~~~~~~~~~ -.. todo:: Add some description about BDM. +Simply speaking, Block Device Mapping describes how block devices are +exposed to the server. + +For some historical reasons, nova has two ways to mention the block device +mapping in server creation request body: + +- ``block_device_mapping``: This is the legacy way and supports backward + compatibility for EC2 API. +- ``block_device_mapping_v2``: This is the recommended format to specify + Block Device Mapping information in server creation request body. + +Users cannot mix the two formats in the same request. + +For more information, refer to `Block Device Mapping +<https://docs.openstack.org/nova/latest/user/block-device-mapping.html>`_. + +For the full list of ``block_device_mapping_v2`` parameters available when +creating a server, see the `API reference +<https://developer.openstack.org/api-ref/compute/?expanded=create-server-detail#create-server>`_. + +**Example for block_device_mapping_v2** + +This will create a 100GB size volume type block device from an image with UUID +of ``bb02b1a3-bc77-4d17-ab5b-421d89850fca``. It will be used as the first order +boot device (``boot_index=0``), and this block device will not be deleted after +we terminate the server. Note that the ``imageRef`` parameter is not required +in this case since we are creating a volume-backed server. + +.. code-block:: json + + { + "server": { + "name": "volume-backed-server-test", + "flavorRef": "52415800-8b69-11e0-9b19-734f1195ff37", + "block_device_mapping_v2": [ + { + "boot_index": 0, + "uuid": "bb02b1a3-bc77-4d17-ab5b-421d89850fca", + "volume_size": "100", + "source_type": "image", + "destination_type": "volume", + "delete_on_termination": false + } + ] + } + } Scheduler Hints ~~~~~~~~~~~~~~~