From c8edb8ce72759007b9ce5fbe4fbd5b9c5724e17b Mon Sep 17 00:00:00 2001 From: Matt Riedemann Date: Tue, 12 Jun 2018 12:50:12 -0400 Subject: [PATCH] api-ref: expand on various bdm parameters Some of the block_device_mapping_v2 parameter descriptions were lacking details on valid values, combinations, restrictions and how things get linked together, for example, to get a swap bdm. This fills in the details and re-words things in some places for clarity. The mention of the libvirt driver in the guest_format for non-swap ephemeral block devices is removed since (1) it's overly confusing and (2) API users shouldn't know or care if the hypervisor running their server is libvirt or not. The point is, if you want swap, ask for swap, and if you want ephemeral, specify one of the other values. Then you get what you get and you don't throw a fit. Change-Id: Ia7e49f28e2f410ada5c2f4c2e3a13ffd97e54654 --- api-ref/source/parameters.yaml | 51 +++++++++++++++++++++++++++------- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index b6e3ecdb78..4aac6c8831 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -1791,10 +1791,13 @@ block_device_mapping_v2: type: array block_device_uuid: description: | - This is the uuid of source resource. The uuid is point to different resource - based on the source_type. For example, if source_type is ``image`` as the above - sample, the block device is created based on the specified image which is gotten - from the image service. + This is the uuid of source resource. The uuid points to different resources + based on the ``source_type``. For example, if ``source_type`` is ``image``, + the block device is created based on the specified image which is retrieved + from the image service. Similarly, if ``source_type`` is ``snapshot`` then + the uuid refers to a volume snapshot in the block storage service. If + ``source_type`` is ``volume`` then the uuid refers to a volume in the block + storage service. in: body required: false type: string @@ -2120,7 +2123,11 @@ description: type: string destination_type: description: | - Defines where the volume comes from. A valid value is ``local`` or ``volume``. + Defines where the block device mapping will reside. Valid values are: + + * ``local``: The ephemeral disk resides local to the compute host on + which the server runs + * ``volume``: The persistent volume is stored in the block storage service in: body required: false type: string @@ -3124,8 +3131,15 @@ group_id: guest_format: description: | Specifies the guest server disk file system format, such as ``ext2``, - ``ext3``, ``ext4``, ``xfs`` or ``swap``. This parameter affects only - the libvirt virt driver. + ``ext3``, ``ext4``, ``xfs`` or ``swap``. + + Swap block device mappings have the following restrictions: + + * The ``source_type`` must be ``blank`` + * The ``destination_type`` must be ``local`` + * There can only be one swap disk per server + * The size of the swap disk must be less than or equal to the ``swap`` + size of the flavor in: body required: false type: string @@ -5930,9 +5944,26 @@ snapshots: type: array source_type: description: | - The source type of the volume. A valid value is ``blank``, ``snapshot``, - ``volume``, or ``image``. If ``no_device`` is not specified, - this parameter is required. + The source type of the block device. Valid values are: + + * ``blank``: Depending on the ``destination_type`` and ``guest_format``, + this will either be a blank persistent volume or an ephemeral (or swap) + disk local to the compute host on which the server resides + * ``image``: This is only valid with ``destination_type=volume``; creates + an image-backed volume in the block storage service and attaches it to + the server + * ``snapshot``: This is only valid with ``destination_type=volume``; + creates a volume backed by the given volume snapshot referenced via the + ``block_device_mapping_v2.uuid`` parameter and attaches it to the server + * ``volume``: This is only valid with ``destination_type=volume``; uses + the existing persistent volume referenced via the + ``block_device_mapping_v2.uuid`` parameter and attaches it to the server + + This parameter is required unless ``block_device_mapping_v2.no_device`` is + specified. + + See `Block Device Mapping in Nova `_ + for more details on valid source and destination types. in: body required: false type: string