4.2. Manage Volumes

A volume is a block storage device that provides persistent storage to OpenStack instances.

4.2.1. Basic Volume Usage and Configuration

The following procedures describe how to perform basic end-user volume management. These procedures do not require administrative privileges.

4.2.1.1. Create a Volume

  1. In the dashboard, select Project > Compute > Volumes.
  2. Click Create Volume, and edit the following fields:
    Field Description
    Volume name Name of the volume.
    Description Optional, short description of the volume.
    Type
    Optional volume type (see Section 4.2.4, “Group Volume Settings with Volume Types”).
    If you have multiple Block Storage back ends, you can use this to select a specific back end. See Section 4.2.1.2, “Specify Back End for Volume Creation” for details.
    Size (GB) Volume size (in gigabytes).
    Availability Zone
    Availability zones (logical server groups), along with host aggregates, are a common method for segregating resources within OpenStack. Availability zones are defined during installation. For more information on availability zones and host aggregates, see Section 3.4, “Manage Host Aggregates”.
  3. Specify a Volume Source:
    Source Description
    No source, empty volume The volume will be empty, and will not contain a file system or partition table.
    Snapshot
    Use an existing snapshot as a volume source. If you select this option, a new Use snapshot as a source list appears; you can then choose a snapshot from the list. For more information about volume snapshots, refer to Section 4.2.1.8, “Create, Clone, or Delete Volume Snapshots”.
    Image Use an existing image as a volume source. If you select this option, a new Use image as a source lists appears; you can then choose an image from the list.
    Volume Use an existing volume as a volume source. If you select this option, a new Use volume as a source list appears; you can then choose a volume from the list.
  4. Click Create Volume. After the volume is created, its name appears in the Volumes table.

4.2.1.2. Specify Back End for Volume Creation

You can configure the Block Storage service to use multiple back ends. For example, Configure OpenStack to Use an NFS Back End provides step-by-step instructions on how to configure the Block Storage service to use an NFS share alongside the default back end.
Whenever multiple Block Storage back ends are configured, you will also need to create a volume type for each back end. You can then use the type to specify which back end should be used for a created volume. For more information about volume types, see Section 4.2.4, “Group Volume Settings with Volume Types”.
To specify a back end when creating a volume, select its corresponding volume type from the Type drop-down list (see Section 4.2.1.1, “Create a Volume”).
If you do not specify a back end during volume creation, the Block Storage service will automatically choose one for you. By default, the service will choose the back end with the most available free space. You can also configure the Block Storage service to choose randomly among all available back ends instead; for more information, see Section 4.2.7, “Configure How Volumes are Allocated to Multiple Back Ends”.

4.2.1.3. Edit a Volume's Name or Description

  1. In the dashboard, select Project > Compute > Volumes.
  2. Select the volume's Edit Volume button.
  3. Edit the volume name or description as required.
  4. Click Edit Volume to save your changes.
Note
To create an encrypted volume, you must first have a volume type configured specifically for volume encryption. In addition, both Compute and Block Storage services must be configured to use the same static key. For information on how to set up the requirements for volume encryption, refer to Section 4.2.6, “Encrypt Volumes with Static Keys”.

4.2.1.4. Delete a Volume

  1. In the dashboard, select Project > Compute > Volumes.
  2. In the Volumes table, select the volume to delete.
  3. Click Delete Volumes.
Note
A volume cannot be deleted if it has existing snapshots. For instructions on how to delete snapshots, see Section 4.2.1.8, “Create, Clone, or Delete Volume Snapshots”.

4.2.1.5. Attach and Detach a Volume to an Instance

Instances can use a volume for persistent storage. A volume can only be attached to one instance at a time. For more information on instances, see Section 3.1, “Manage Instances”.

Procedure 4.1. Attach a Volume from an Instance

  1. In the dashboard, select Project > Compute > Volumes.
  2. Select the volume's Edit Attachments action. If the volume is not attached to an instance, the Attach To Instance drop-down list is visible.
  3. From the Attach To Instance list, select the instance to which you wish to attach the volume.
  4. Click Attach Volume.

Procedure 4.2. Detach a Volume From an Instance

  1. In the dashboard, select Project > Compute > Volumes.
  2. Select the volume's Edit Attachments action. If the volume is attached to an instance, the instance's name is displayed in the Attachments table.
  3. Click Detach Volume in this and the next dialog screen.

4.2.1.6. Set a Volume to Read-Only

You can give multiple users shared access to a single volume without allowing them to edit its contents. To do so, set the volume to read-only using the following command: 
# cinder readonly-mode-update VOLUME true
Replace VOLUME with the ID of the target volume.
To set a read-only volume back to read-write, run: 
# cinder readonly-mode-update VOLUME false

4.2.1.7. Change a Volume's Owner

To change a volume's owner, you will have to perform a volume transfer. A volume transfer is initiated by the volume's owner, and the volume's change in ownership is complete after the transfer is accepted by the volume's new owner.
  1. From the command line, log in as the volume's current owner.
  2. List the available volumes: 
    # cinder list
  3. Initiate the volume transfer: 
    # cinder transfer-create VOLUME
    Where VOLUME is the name or ID of the volume you wish to transfer.

    Example 4.1. 

    # cinder transfer-create samplevolume
+------------+--------------------------------------+
|  Property  |                Value                 |
+------------+--------------------------------------+
|  auth_key  |           f03bf51ce7ead189           |
| created_at |      2014-12-08T03:46:31.884066      |
|     id     | 3f5dc551-c675-4205-a13a-d30f88527490 |
|    name    |                 None                 |
| volume_id  | bcf7d015-4843-464c-880d-7376851ca728 |
+------------+--------------------------------------+
    The cinder transfer-create command clears the ownership of the volume and creates an id and auth_key for the transfer. These values can be given to, and used by, another user to accept the transfer and become the new owner of the volume.
  4. The new user can now claim ownership of the volume. To do so, the user should first log in from the command line and run: 
    # cinder transfer-accept TRANSFERID TRANSFERKEY
    Where TRANSFERID and TRANSFERKEY are the id and auth_key values returned by the cinder transfer-create command, respectively.

    Example 4.2. 

    # cinder transfer-accept 3f5dc551-c675-4205-a13a-d30f88527490 f03bf51ce7ead189
Note
You can view all available volume transfers using: 
# cinder transfer-list

4.2.1.8. Create, Clone, or Delete Volume Snapshots

You can preserve a volume's state at a specific point in time by creating a volume snapshot. You can then use the snapshot to clone new volumes.
Warning
Creating a snapshot of a volume that is attached to an instance may corrupt the snapshot. For instructions on how to detach a volume from an instance, see Procedure 4.2, “Detach a Volume From an Instance”.
Note
Volume backups are different from snapshots. Backups preserve the data contained in the volume, whereas snapshots preserve the state of a volume at a specific point in time. In addition, you cannot delete a volume if it has existing snapshots. Volume backups are used to prevent data loss, whereas snapshots are used to facilitate cloning.
For more information about volume backups, refer to Section 4.2.2, “Back Up and Restore a Volume”.
To create a volume snapshot:
  1. In the dashboard, select Project > Compute > Volumes.
  2. Select the target volume's Create Snapshot action.
  3. Provide a Snapshot Name for the snapshot and click Create a Volume Snapshot. The Volume Snapshots tab displays all snapshots.
You can clone new volumes from a snapshot once it appears in the Volume Snapshots table. To do so, select the snapshot's Create Volume action. For more information about volume creation, see Section 4.2.1.1, “Create a Volume”.
To delete a snapshot, select its Delete Volume Snapshot action.
If your OpenStack deployment uses a Red Hat Ceph back end, see Section 4.2.1.8.1, “Protected and Unprotected Snapshots in a Red Hat Ceph Back End” for more information on snapshot security and troubleshooting.
4.2.1.8.1. Protected and Unprotected Snapshots in a Red Hat Ceph Back End
When using Red Hat Ceph as a back end for your OpenStack deployment, you can set a snapshot to protected in the back end. Attempting to delete protected snapshots through OpenStack (as in, through the dashboard or the cinder snapshot-delete command) will fail.
When this occurs, set the snapshot to unprotected in the Red Hat Ceph back end first. Afterwards, you should be able to delete the snapshot through OpenStack as normal.
For related instructions, see Protecting a Snapshot and Unprotecting a Snapshot.

4.2.1.9. Upload a Volume to the Image Service

You can upload an existing volume as an image to the Image service directly. To do so:
  1. In the dashboard, select Project > Compute > Volumes.
  2. Select the target volume's Upload to Image action.
  3. Provide an Image Name for the volume and select a Disk Format from the list.
  4. Click Upload. The QEMU disk image utility uploads a new image of the chosen format using the name you provided.
To view the uploaded image, select Project > Compute > Images. The new image appears in the Images table. For information on how to use and configure images, see Section 4.1, “Manage Images”.

4.2.2. Back Up and Restore a Volume

A volume backup is a full, persistent copy of a volume's contents. Volume backups are typically created as object stores, and therefore are managed through the Object Storage service.
When creating a volume backup, all of the backup's metadata is stored in the Block Storage service's database. The cinder utility uses this metadata when restoring a volume from the backup. As such, when recovering from a catastrophic database loss, you must restore the Block Storage service's database first before restoring any volumes from backups. This also presumes that the Block Storage service database is being restored with all the original volume backup metadata intact.
If you wish to configure only a subset of volume backups to survive a catastrophic database loss, you can also export the backup's metadata. In doing so, you can then re-import the metadata to the Block Storage database later on, and restore the volume backup as normal.
Note
Volume backups are different from snapshots. Backups preserve the data contained in the volume, whereas snapshots preserve the state of a volume at a specific point in time. In addition, you cannot delete a volume if it has existing snapshots. Volume backups are used to prevent data loss, whereas snapshots are used to facilitate cloning.
For more information about volume snapshots, refer to Section 4.2.1.8, “Create, Clone, or Delete Volume Snapshots”.

4.2.2.1. Create a Volume Backup

  1. As a user with administrative privileges, view the ID or Display Name of the volume you wish to back-up: 
    # cinder list
  2. Back up the volume: 
    # cinder backup-create VOLUME
    Where VOLUME is the ID or Display Name of the volume you wish to back-up.

    Example 4.3. 

    # cinder backup-create volumename
+-----------+--------------------------------------+
|  Property |                Value                 |
+-----------+--------------------------------------+
|     id    | e9d15fc7-eeae-4ca4-aa72-d52536dc551d |
|    name   |                 None                 |
| volume_id | 5f75430a-abff-4cc7-b74e-f808234fa6c5 |
+-----------+--------------------------------------+
    Note that the volume_id of the resulting backup is identical to the ID of volumename.
  3. Verify that the volume backup creation is complete: 
    # cinder backup-list
    The volume backup creation is complete when the Status of the backup entry is available.
At this point, you can also export and store the volume backup's metadata. This allows you to restore the volume backup, even if the Block Storage database suffers a catastrophic loss. To do so, run: 
# cinder --os-volume-api-version 2 backup-export BACKUPID
Where BACKUPID is the ID or name of the volume backup.

Example 4.4. 

# cinder --os-volume-api-version 2 backup-export e9d15fc7-eeae-4ca4-aa72-d52536dc551d
+----------------+------------------------------------------------------------------+
|    Property    |                                    Value                         |
+----------------+------------------------------------------------------------------+
| backup_service |                         cinder.backup.drivers.swift              |
|   backup_url   | eyJzdGF0dXMi...                                                  |
|                | ...c2l6ZSI6IDF9                                                  |
+----------------+------------------------------------------------------------------+
The volume backup metadata consists of the backup_service and backup_url values.

4.2.2.2. Restore a Volume After a Block Storage Database Loss

Typically, a Block Storage database loss prevents you from restoring a volume backup. This is because the Block Storage database contains metadata required by the volume backup. This metadata consists of backup_service and backup_url values, which you can export after creating the volume backup (as shown in Section 4.2.2.1, “Create a Volume Backup”).
If you exported and stored this metadata, then you can import it to a new Block Storage database (thereby allowing you to restore the volume backup).
  1. As a user with administrative privileges, run: 
    # cinder --os-volume-api-version 2 backup-import backup_service backup_url
    Where backup_service and backup_url are from the metadata you exported.

    Example 4.5. 

    Using the exported sample metadata from Section 4.2.2.1, “Create a Volume Backup”: 
    # cinder --os-volume-api-version 2 backup-import cinder.backup.drivers.swift eyJzdGF0dXMi...c2l6ZSI6IDF9
+----------+--------------------------------------+
| Property |                Value                 |
+----------+--------------------------------------+
|    id    | 77951e2f-4aff-4365-8c64-f833802eaa43 |
|   name   |                 None                 |
+----------+--------------------------------------+
  2. After the metadata is imported into the Block Storage service database, you can restore the volume as normal (see Section 4.2.2.3, “Restore a Volume from a Backup”).

4.2.2.3. Restore a Volume from a Backup

  1. As a user with administrative privileges, find the ID of the volume backup you wish to use: 
    # cinder backup-list
    The Volume ID should match the ID of the volume you wish to restore.
  2. Restore the volume backup: 
    # cinder backup-restore BACKUP_ID
    Where BACKUP_ID is the ID of the volume backup you wish to use.
  3. If you no longer need the backup, delete it: 
    # cinder backup-delete BACKUP_ID

4.2.3. Migrate a Volume

Only an administrator can migrate volumes; volumes to be migrated cannot be in use nor can they have any snapshots.
  1. As an administrative user, list all available volumes: 
    # cinder list
  2. List the available back ends (hosts) and their respective availability zones: 
    # cinder-manage host list
  3. Initiate the migration: 
    # cinder migrate VOLUME BACKEND
    Where:
    • VOLUME is the ID of the volume to be migrated.
    • BACKEND is the back end to where the volume should be migrated.
  4. View the current status of the volume to be migrated: 
    # cinder show VOLUME

    Example 4.6. 

    # cinder show 45a85c3c-3715-484d-ab5d-745da0e0bd5a
+---------------------------------------+--------------------------------------+
|                Property               |                Value                 |
+---------------------------------------+--------------------------------------+
|                  ...                  |                 ...                  |
|         os-vol-host-attr:host         |                server1               |
|     os-vol-mig-status-attr:migstat    |                 None                 |
|                  ...                  |                 ...                  |
+---------------------------------------+--------------------------------------+
    During migration, note the following attributes:
    os-vol-host-attr:host
    The volume's current back end. Once the migration completes, this displays the target back end (namely, BACKEND).
    os-vol-mig-status-attr:migstat
    The status of the migration. A status of None means a migration is no longer in progress.

4.2.4. Group Volume Settings with Volume Types

OpenStack allows you to create volume types, which allows you apply the type's associated settings when creating a volume (Section 4.2.1.1, “Create a Volume”). For example, you can associate:
Settings are associated with volume types using key-value pairs called Extra Specs. When you specify a volume type during volume creation, the Block Storage scheduler applies these key/value pairs as settings. You can associate multiple key/value pairs to the same volume type.

Example 4.7. 

Volume types provide the capability to provide different users with storage tiers. By associating specific performance, resilience, and other settings as key/value pairs to a volume type, you can map tier-specific settings to different volume types. You can then apply tier settings when creating a volume by specifying the corresponding volume type.
Note
Available and supported Extra Specs vary per volume driver. Consult your volume driver's documentation for a list of valid Extra Specs.

4.2.4.1. Create and Configure a Volume Type

  1. As an admin user in the dashboard, select Admin > Volumes > Volume Types.
  2. Click Create Volume Type.
  3. Enter the volume type name in the Name field.
  4. Click Create Volume Type. The new type appears in the Volume Types table.
  5. Select the volume type's View Extra Specs action.
  6. Click Create, and specify the Key and Value. The key/value pair must be valid; otherwise, specifying the volume type during volume creation will result in an error.
  7. Click Create. The associated setting (key/value pair) now appears in the Extra Specs table.
Note
You can also associate a QOS Spec to the volume type. For details, refer to Section 4.2.5.2, “Associate a QOS Spec with a Volume Type”.

4.2.4.2. Edit a Volume Type

  1. As an admin user in the dashboard, select Admin > Volumes > Volume Types.
  2. In the Volume Types table, select the volume type's View Extra Specs action.
  3. On the Extra Specs table of this page, you can:
    • Add a new setting to the volume type. To do this, click Create, and specify the key/value pair of the new setting you wish to associate to the volume type.
    • Edit an existing setting associated with the volume type. To do this, select the settings Edit action.
    • Delete existing settings associated with the volume type. To do this, select the extra specs' check box and click Delete Extra Specs in this and the next dialog screen.

4.2.4.3. Delete a Volume Type

To delete a volume type, select its corresponding checkboxes from the Volume Types table and click Delete Volume Types.

4.2.5. Use Quality-of-Service Specifications

You can map multiple performance settings to a single Quality-of-Service specification (QOS Specs). Doing so allows you to provide performance tiers for different user types.
Performance settings are mapped as key/value pairs to QOS Specs, similar to the way volume settings are associated to a volume type. However, QOS Specs are different from volume types in the following respects:
  • QOS Specs are used to apply performance settings, which include limiting read/write operations to disks. Available and supported performance settings vary per storage driver.
    To determine which QOS Specs are supported by your back end, consult the documentation of your back end device's volume driver.
  • Volume types are directly applied to volumes, whereas QOS Specs are not. Rather, QOS Specs are associated to volume types. During volume creation, specifying a volume type also applies the performance settings mapped to the volume type's associated QOS Specs.

4.2.5.1. Create and Configure a QOS Spec

As an administrator, you can create and configure a QOS Spec through the QOS Specs table. You can associate more than one key/value pair to the same QOS Spec.
  1. As an admin user in the dashboard, select Admin > Volumes > Volume Types.
  2. On the QOS Specs table, click Create QOS Spec.
  3. Enter a name for the QOS Spec.
  4. In the Consumer field, specify where the QOS policy should be enforced:

    Table 4.1. Consumer Types

    Type Description
    back-end QOS policy will be applied to the Block Storage back end.
    front-end QOS policy will be applied to Compute.
    both QOS policy will be applied to both Block Storage and Compute.
  5. Click Create. The new QOS Spec should now appear in the QOS Specs table.
  6. In the QOS Specs table, select the new spec's Manage Specs action.
  7. Click Create, and specify the Key and Value. The key/value pair must be valid; otherwise, specifying a volume type associated with this QOS Spec during volume creation will fail.
  8. Click Create. The associated setting (key/value pair) now appears in the Key-Value Pairs table.

4.2.5.2. Associate a QOS Spec with a Volume Type

As an administrator, you can associate a QOS Spec to an existing volume type using the Volume Types table.
  1. As an administrator in the dashboard, select Admin > Volumes > Volume Types.
  2. In the Volume Types table, select the type's Manage QOS Spec Association action.
  3. Select a QOS Spec from the QOS Spec to be associated list.
  4. Click Associate. The selected QOS Spec now appears in the Associated QOS Spec column of the edited volume type.

4.2.5.3. Disassociate a QOS Spec from a Volume Type

  1. As an administrator in the dashboard, select Admin > Volumes > Volume Types.
  2. In the Volume Types table, select the type's Manage QOS Spec Association action.
  3. Select 'None' from the QOS Spec to be associated list.
  4. Click Associate. The selected QOS Spec is no longer in the Associated QOS Spec column of the edited volume type.

4.2.6. Encrypt Volumes with Static Keys

Volume encryption helps provide basic data protection in case the volume back-end is either compromised or outright stolen. The contents of an encrypted volume can only be read with the use of a specific key; both Compute and Block Storage services must be configured to use the same key in order for instances to use encrypted volumes. This section describes how to configure an OpenStack deployment to use a single key for encrypting volumes.

4.2.6.1. Configure a Static Key

The first step in implementing basic volume encryption is to set a static key. This key must be a hex string, which will be used by the Block Storage volume service (namely, openstack-cinder-volume) and all Compute services (openstack-nova-compute). To configure both services to use this key, set the key as the fixed_key value in the [keymgr] section of both service's respective configuration files.
  1. From the command line, log in as root to the node hosting openstack-cinder-volume.
  2. Set the static key: 
    # openstack-config --set /etc/cinder/cinder.conf keymgr fixed_key HEX_KEY
    Replace HEX_KEY with a 16-digit alphanumeric hex key (for example, 0000000000000000000000000000000000000000000000000000000000000000).
  3. Restart the Block Storage volume service: 
    # openstack-service restart cinder-volume
  4. Log in to the node hosting openstack-nova-compute, and set the same static key: 
    # openstack-config --set /etc/nova/nova.conf keymgr fixed_key HEX_KEY
    Note
    If you have multiple Compute nodes (multiple nodes hosting openstack-nova-compute), then you need to set the same static key in /etc/nova/nova.conf of each node.
  5. Restart the Compute service: 
    # openstack-service restart nova-compute
    Note
    Likewise, if you set the static key on multiple Compute nodes, you need to restart the openstack-nova-compute service on each node as well.
At this point, both Compute and Block Storage volume services can now use the same static key to encrypt/decrypt volumes. That is, new instances will be able to use volumes encrypted with the static key (HEX_KEY).

4.2.6.2. Configure Volume Type Encryption

To create volumes encrypted with the static key from Section 4.2.6.1, “Configure a Static Key”, you need an encrypted volume type. Configuring a volume type as encrypted involves setting what provider class, cipher, and key size it should use. To do so, run: 
# cinder encryption-type-create --cipher aes-xts-plain64 --key_size BITSIZE --control_location front-end VOLTYPE nova.volume.encryptors.luks.LuksEncryptor
Where:
  • BITSIZE is the key size (for example, 512 for a 512-bit key).
  • VOLTYPE is the name of the volume type you want to encrypt.
This command sets the nova.volume.encryptors.luks.LuksEncryptor provider class and aes-xts-plain64 cipher. As of this release, this is the only supported class/cipher configuration for volume encryption.
Once you have an encrypted volume type, you can invoke it to automatically create encrypted volumes. Specifically, select the encrypted volume type from the Type drop-down list in the Create Volume window (see to Section 4.2.1, “Basic Volume Usage and Configuration”).

4.2.7. Configure How Volumes are Allocated to Multiple Back Ends

If the Block Storage service is configured to use multiple back ends, you can use configured volume types to specify where a volume should be created. For details, see Section 4.2.1.2, “Specify Back End for Volume Creation”.
The Block Storage service will automatically choose a back end if you do not specify one during volume creation. Block Storage sets the first defined back end as a default; this back end will be used until it runs out of space. At that point, Block Storage will set the second defined back end as a default, and so on.
If this is not suitable for your needs, you can use the filter scheduler to control how Block Storage should select back ends. This scheduler can use different filters to triage suitable back ends, such as:
AvailabilityZoneFilter
Filters out all back ends that do not meet the availability zone requirements of the requested volume
CapacityFilter
Selects only back ends with enough space to accommodate the volume
CapabilitiesFilter
Selects only back ends that can support any specified settings in the volume
To configure the filter scheduler:
  1. Enable the FilterScheduler driver. 
    # openstack-config --set /etc/cinder/cinder.conf DEFAULT scheduler_driver cinder.scheduler.filter_scheduler.FilterScheduler
  2. Set which filters should be active: 
    # openstack-config --set /etc/cinder/cinder.conf DEFAULT scheduler_default_filters AvailabilityZoneFilter,CapacityFilter,CapabilitiesFilter
  3. Configure how the scheduler should select a suitable back end. If you want the scheduler:
    • To always choose the back end with the most available free space, run: 
      # openstack-config --set /etc/cinder/cinder.conf DEFAULT scheduler_default_weighers AllocatedCapacityWeigher
# openstack-config --set /etc/cinder/cinder.conf DEFAULT allocated_capacity_weight_multiplier -1.0
    • To choose randomly among all suitable back ends, run: 
      # openstack-config --set /etc/cinder/cinder.conf DEFAULT scheduler_default_weighers ChanceWeigher
  4. Restart the Block Storage scheduler to apply your settings: 
    # openstack-service restart openstack-cinder-scheduler