ceph/src/spdk/doc/lvol.md

   1 # Logical Volumes {#logical_volumes}
   2
   3 The Logical Volumes library is a flexible storage space management system. It provides creating and managing virtual block devices with variable size. The SPDK Logical Volume library is built on top of @ref blob.
   4
   5 # Terminology {#lvol_terminology}
   6
   7 ## Logical volume store {#lvs}
   8
   9 * Shorthand:  lvolstore, lvs
  10 * Type name:  struct spdk_lvol_store
  11
  12 A logical volume store uses the super blob feature of blobstore to hold uuid (and in future other metadata). Blobstore types are implemented in blobstore itself, and saved on disk. An lvolstore will generate a UUID on creation, so that it can be uniquely identified from other lvolstores.
  13 By default when creating lvol store data region is unmapped. Optional --clear-method parameter can be passed on creation to change that behavior to writing zeroes or performing no operation.
  14
  15 ## Logical volume {#lvol}
  16
  17 * Shorthand: lvol
  18 * Type name: struct spdk_lvol
  19
  20 A logical volume is implemented as an SPDK blob created from an lvolstore. An lvol is uniquely identified by its UUID. Lvol additional can have alias name.
  21
  22 ## Logical volume block device {#lvol_bdev}
  23
  24 * Shorthand: lvol_bdev
  25 * Type name: struct spdk_lvol_bdev
  26
  27 Representation of an SPDK block device (spdk_bdev) with an lvol implementation.
  28 A logical volume block device translates generic SPDK block device I/O (spdk_bdev_io) operations into the equivalent SPDK blob operations. Combination of lvol name and lvolstore name gives lvol_bdev alias name in a form "lvs_name/lvol_name". block_size of the created bdev is always 4096, due to blobstore page size. Cluster_size is configurable by parameter.
  29 Size of the new bdev will be rounded up to nearest multiple of cluster_size.
  30 By default lvol bdevs claim part of lvol store equal to their set size. When thin provision option is enabled, no space is taken from lvol store until data is written to lvol bdev.
  31 By default when deleting lvol bdev or resizing down, allocated clusters are unmapped. Optional --clear-method parameter can be passed on creation to change that behavior to writing zeroes or performing no operation.
  32
  33 ## Thin provisioning {#lvol_thin_provisioning}
  34
  35 Thin provisioned lvols rely on dynamic cluster allocation (e.g. when the first write operation on a cluster is performed), only space required to store data is used and unallocated clusters are obtained from underlying device (e.g. zeroes_dev).
  36
  37 Sample write operations of thin provisioned blob are shown on the diagram below:
  38
  39 ![Writing clusters to the thin provisioned blob](lvol_thin_provisioning_write.svg)
  40
  41 Sample read operations and the structure of thin provisioned blob are shown on the diagram below:
  42
  43 ![Reading clusters from thin provisioned blob](lvol_thin_provisioning.svg)
  44
  45 ## Snapshots and clone {#lvol_snapshots}
  46
  47 Logical volumes support snapshots and clones functionality. User may at any given time create snapshot of existing logical volume to save a backup of current volume state.
  48 When creating snapshot original volume becomes thin provisioned and saves only incremental differences from its underlying snapshot. This means that every read from unallocated cluster is actually a read from the snapshot and
  49 every write to unallocated cluster triggers new cluster allocation and data copy from corresponding cluster in snapshot to the new cluster in logical volume before the actual write occurs.
  50
  51 The read operation is performed as shown in the diagram below:
  52 ![Reading cluster from clone](lvol_clone_snapshot_read.svg)
  53
  54 The write operation is performed as shown in the diagram below:
  55 ![Writing cluster to the clone](lvol_clone_snapshot_write.svg)
  56
  57 User may also create clone of existing snapshot that will be thin provisioned and it will behave in the same way as logical volume from which snapshot is created.
  58 There is no limit of clones and snapshots that may be created as long as there is enough space on logical volume store. Snapshots are read only. Clones may be created only from snapshots or read only logical volumes.
  59
  60 A snapshot can be removed only if there is a single clone on top of it. The relation chain will be updated accordingly. The cluster map of clone and snapshot will be merged and entries for unallocated clusters in the clone
  61 will be updated with addresses from the snapshot cluster map. The entire operation modifies metadata only - no data is copied during this process.
  62
  63 ## Inflation {#lvol_inflation}
  64
  65 Blobs can be inflated to copy data from backing devices (e.g. snapshots) and allocate all remaining clusters. As a result of this operation all dependencies for the blob are removed.
  66
  67 ![Removing backing blob and bdevs relations using inflate call](lvol_inflate_clone_snapshot.svg)
  68
  69 ## Decoupling {#lvol_decoupling}
  70
  71 Blobs can be decoupled from their parent blob by copying data from backing devices (e.g. snapshots) for all allocated clusters. Remaining unallocated clusters are kept thin provisioned.
  72 Note: When decouple is performed, only single dependency is removed. To remove all dependencies in a chain of blobs depending on each other, multiple calls need to be issued.
  73
  74 # Configuring Logical Volumes
  75
  76 There is no static configuration available for logical volumes. All configuration is done trough RPC. Information about logical volumes is kept on block devices.
  77
  78 # RPC overview {#lvol_rpc}
  79
  80 RPC regarding lvolstore:
  81
  82 ```
  83 bdev_lvol_create_lvstore [-h] [-c CLUSTER_SZ] bdev_name lvs_name
  84     Constructs lvolstore on specified bdev with specified name. During
  85     construction bdev is unmapped at initialization and all data is
  86     erased. Then original bdev is claimed by
  87     SPDK, but no additional spdk bdevs are created.
  88     Returns uuid of created lvolstore.
  89     Optional parameters:
  90     -h  show help
  91     -c  CLUSTER_SZ Specifies the size of cluster. By default its 4MiB.
  92     --clear-method specify data region clear method "none", "unmap" (default), "write_zeroes"
  93 bdev_lvol_delete_lvstore [-h] [-u UUID] [-l LVS_NAME]
  94     Destroy lvolstore on specified bdev. Removes lvolstore along with lvols on
  95     it. User can identify lvol store by UUID or its name. Note that destroying
  96     lvolstore requires using this call, while deleting single lvol requires
  97     using bdev_lvol_delete rpc call.
  98     optional arguments:
  99     -h, --help  show help
 100 bdev_lvol_get_lvstores [-h] [-u UUID] [-l LVS_NAME]
 101     Display current logical volume store list
 102     optional arguments:
 103     -h, --help  show help
 104     -u UUID, --uuid UUID  show details of specified lvol store
 105     -l LVS_NAME, --lvs_name LVS_NAME  show details of specified lvol store
 106 bdev_lvol_rename_lvstore [-h] old_name new_name
 107     Change logical volume store name
 108     optional arguments:
 109     -h, --help  show this help message and exit
 110 ```
 111
 112 RPC regarding lvol and spdk bdev:
 113
 114 ```
 115 bdev_lvol_create [-h] [-u UUID] [-l LVS_NAME] [-t] [-c CLEAR_METHOD] lvol_name size
 116     Creates lvol with specified size and name on lvolstore specified by its uuid
 117     or name. Then constructs spdk bdev on top of that lvol and presents it as spdk bdev.
 118     User may use -t switch to create thin provisioned lvol.
 119     Returns the name of new spdk bdev
 120     optional arguments:
 121     -h, --help  show help
 122     -c, --clear-method specify data clusters clear method "none", "unmap" (default), "write_zeroes"
 123 bdev_get_bdevs [-h] [-b NAME]
 124     User can view created bdevs using this call including those created on top of lvols.
 125     optional arguments:
 126     -h, --help  show help
 127     -b NAME, --name NAME  Name of the block device. Example: Nvme0n1
 128 bdev_lvol_delete [-h] bdev_name
 129     Deletes a logical volume previously created by bdev_lvol_create.
 130     optional arguments:
 131     -h, --help  show help
 132 bdev_lvol_snapshot [-h] lvol_name snapshot_name
 133     Create a snapshot with snapshot_name of a given lvol bdev.
 134     optional arguments:
 135     -h, --help  show help
 136 bdev_lvol_clone [-h] snapshot_name clone_name
 137     Create a clone with clone_name of a given lvol snapshot.
 138     optional arguments:
 139     -h, --help  show help
 140 bdev_lvol_rename [-h] old_name new_name
 141     Change lvol bdev name
 142     optional arguments:
 143     -h, --help  show help
 144 bdev_lvol_resize [-h] name size
 145     Resize existing lvol bdev
 146     optional arguments:
 147     -h, --help  show help
 148 bdev_lvol_set_read_only [-h] name
 149     Mark lvol bdev as read only
 150     optional arguments:
 151     -h, --help  show help
 152 bdev_lvol_inflate [-h] name
 153     Inflate lvol bdev
 154     optional arguments:
 155     -h, --help  show help
 156 bdev_lvol_decouple_parent [-h] name
 157     Decouple parent of a logical volume
 158     optional arguments:
 159     -h, --help  show help
 160 ```