Chapter 2. Block Storage and Volumes

Available and supported Extra Specs vary per back end driver. Consult the driver’s documentation for a list of valid Extra Specs.

Alternatively, you can query the Block Storage host directly to determine which well-defined standard Extra Specs are supported by its driver. Start by logging in (through the command line) to the node hosting the Block Storage service. Then:

# cinder service-list

This command will return a list containing the host of each Block Storage service (cinder-backup, cinder-scheduler, and cinder-volume). For example:

+------------------+---------------------------+------+---------
|      Binary      |            Host           | Zone |  Status ...
+------------------+---------------------------+------+---------
|  cinder-backup   |   localhost.localdomain   | nova | enabled ...
| cinder-scheduler |   localhost.localdomain   | nova | enabled ...
|  cinder-volume   | localhost.localdomain@lvm | nova | enabled ...
+------------------+---------------------------+------+---------

To display the driver capabilities (and, in turn, determine the supported Extra Specs) of a Block Storage service, run:

# cinder get-capabilities VOLSVCHOST

Where VOLSVCHOST is the complete name of the cinder-volume's host. For example:

# cinder get-capabilities localhost.localdomain@lvm
    +---------------------+-----------------------------------------+
    |     Volume stats    |                        Value            |
    +---------------------+-----------------------------------------+
    |     description     |                         None            |
    |     display_name    |                         None            |
    |    driver_version   |                        3.0.0            |
    |      namespace      | OS::Storage::Capabilities::localhost.loc...
    |      pool_name      |                         None            |
    |   storage_protocol  |                        iSCSI            |
    |     vendor_name     |                     Open Source         |
    |      visibility     |                         None            |
    | volume_backend_name |                         lvm             |
    +---------------------+-----------------------------------------+
    +--------------------+------------------------------------------+
    | Backend properties |                        Value             |
    +--------------------+------------------------------------------+
    |    compression     |      {u'type': u'boolean', u'description'...
    |        qos         |              {u'type': u'boolean', u'des ...
    |    replication     |      {u'type': u'boolean', u'description'...
    | thin_provisioning  | {u'type': u'boolean', u'description': u'S...
    +--------------------+------------------------------------------+

The Backend properties column shows a list of Extra Spec Keys that you can set, while the Value column provides information on valid corresponding values.

By default, all volume types are accessible to all OpenStack tenants. If you need to create volume types with restricted access, you will need to do so through the CLI. For instructions, see Section 2.2.1.5, “Create and Configure Private Volume Types”.

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

By default, all volume types are visible to all tenants. You can override this during volume type creation and set it to private. To do so, you will need to set the type’s Is_Public flag to False.

Private volume types are useful for restricting access to certain volume settings. Typically, these are settings that should only be usable by specific tenants; examples include new back ends or ultra-high performance configurations that are being tested.

To create a private volume type, run:

# cinder --os-volume-api-version 2 type-create --is-public false VTYPE

+ Replace VTYPE with the name of the private volume type.

By default, private volume types are only accessible to their creators. However, admin users can find and view private volume types using the following command:

# cinder --os-volume-api-version 2 type-list --all

This command will list both public and private volume types, and will also include the name and ID of each one. You will need the volume type’s ID to provide access to it.

Access to a private volume type is granted at the tenant level. To grant a tenant access to a private volume type, run:

# cinder --os-volume-api-version 2 type-access-add --volume-type VTYPEID --project-id TENANTID

Where:

To view which tenants have access to a private volume type, run:

# cinder --os-volume-api-version 2 type-access-list --volume-type VTYPE

To remove a tenant from the access list of a private volume type, run:

# cinder --os-volume-api-version 2 type-access-remove --volume-type VTYPE --project-id TENANTID

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.

As an administrator, you can associate a QOS Spec to an existing volume type using the Volume Types table.

To create encrypted volumes, you first need an encrypted volume type. Encrypting a volume type involves setting what provider class, cipher, and key size it should use:

Once you have an encrypted volume type, you can invoke it to automatically create encrypted volumes. For more information on creating a volume type, see ]. Specifically, select the encrypted volume type from the Type drop-down list in the Create Volume window (see to xref:section-volumes_basic[).

You can also re-configure the encryption settings of an encrypted volume type. To do so, select Update Encryption from the Actions column of the volume type. Doing so will launch the Update Volume Type Encryption wizard.

In Project > Compute > Volumes, the Encrypted column in the Volumes table indicates whether the volume is encrypted. If it is, you can click Yes in that column to view the encryption settings.

By default, Block Storage security policy disables consistency groups APIs. You need to enable it here before using the feature. To do so, edit the related consistency group entries in /etc/cinder/policy.json of the node hosting the Block Storage API service (namely, openstack-cinder-api). The entries appear as follows:

"consistencygroup:create" : "group:nobody",
​"consistencygroup:delete": "group:nobody",
​"consistencygroup:update": "group:nobody",
​"consistencygroup:get": "group:nobody",
​"consistencygroup:get_all": "group:nobody",
​"consistencygroup:create_cgsnapshot" : "group:nobody",
​"consistencygroup:delete_cgsnapshot": "group:nobody",
​"consistencygroup:get_cgsnapshot": "group:nobody",
​"consistencygroup:get_all_cgsnapshots": "group:nobody",

For increased security, set the permissions for both consistency group API and volume type management API be identical. The volume type management API is set to "rule:admin_or_owner" by default (in the same /etc/cinder/policy.json file):

"volume_extension:types_manage": "rule:admin_or_owner",

So, to enable the consistency group APIs as recommended, edit their entries as follows:

"consistencygroup:create" : "rule:admin_api",
​"consistencygroup:delete": "rule:admin_api",
​"consistencygroup:update": "rule:admin_api",
​"consistencygroup:get": "rule:admin_api",
​"consistencygroup:get_all": "rule:admin_api",
​"consistencygroup:create_cgsnapshot" : "rule:admin_api",
​"consistencygroup:delete_cgsnapshot": "rule:admin_api",
​"consistencygroup:get_cgsnapshot": "rule:admin_api",
​"consistencygroup:get_all_cgsnapshots": "rule:admin_api",

"consistencygroup:create" : "rule:admin_or_owner",
​"consistencygroup:delete": "rule:admin_or_owner",
​"consistencygroup:update": "rule:admin_or_owner",
​"consistencygroup:get": "rule:admin_or_owner",
​"consistencygroup:get_all": "rule:admin_or_owner",
​"consistencygroup:create_cgsnapshot" : "rule:admin_or_owner",
​"consistencygroup:delete_cgsnapshot": "rule:admin_or_owner",
​"consistencygroup:get_cgsnapshot": "rule:admin_or_owner",
​"consistencygroup:get_all_cgsnapshots": "rule:admin_or_owner",

After enabling the consistency group APIs, restart the Block Storage API service. To do so, log in to any Controller node as the heat-admin user and run:

# pcs resource restart openstack-cinder-api

After enabling the consistency groups API, you can then start creating consistency groups. To do so:

You can change the name or description of a consistency group by selecting Edit Consistency Group from its Action column.

In addition, you can also add or remove volumes from a consistency group directly. To do so:

After adding volumes to a consistency group, you can now create snapshots from it. Before doing so, first log in as admin user from the command line on the node hosting the openstack-cinder-api and run:

# export OS_VOLUME_API_VERSION=2

Doing so will configure the client to use version 2 of openstack-cinder-api.

To list all available consistency groups (along with their respective IDs, which you will need later):

# cinder consisgroup-list

To create snapshots using the consistency group, run:

# cinder cgsnapshot-create --name CGSNAPNAME --description "DESCRIPTION" CGNAMEID

Where:

To display a list of all available consistency group snapshots, run:

# cinder cgsnapshot-list

Consistency groups can also be used to create a whole batch of pre-configured volumes simultaneously. You can do this by cloning an existing consistency group or restoring a consistency group snapshot. Both processes use the same command.

To clone an existing consistency group:

# cinder consisgroup-create-from-src --source-cg CGNAMEID --name CGNAME --description "DESCRIPTION"

Where: - CGNAMEID is the name or ID of the consistency group you want to clone. - CGNAME is the name of your consistency group (optional). - DESCRIPTION is a description of your consistency group (optional).

To create a consistency group from a consistency group snapshot:

# cinder consisgroup-create-from-src --cgsnapshot CGSNAPNAME --name CGNAME --description "DESCRIPTION"

Replace CGSNAPNAME with the name or ID of the snapshot you are using to create the consistency group.

Normally, you can use the dashboard to modify tenant storage quotas, for example, the number of volumes, volume storage, snapshots, or other operational limits that a tenant can have. However, the functionality to modify backup quotas with the dashboard is not yet available.

You must use the command-line interface to modify backup quotas with the cinder quota-update command.

To view the storage quotas of a specific tenant (TENANT_ID), run:

# cinder quota-show TENANT_ID

To update the maximum number of backups (MAXNUM) that can be created in a specific tenant, run:

# cinder quota-update --backups MAXNUM TENANT_ID

To update the maximum total size of all backups (MAXGB) within a specific tenant, run:

# cinder quota-update --backup-gigabytes MAXGB TENANT_ID

To view the storage quota usage of a specific tenant, run:

# cinder quota-usage TENANT_ID

You can now create, view, delete, and restore volume backups through the dashboard. To perform any of these functions, go to the Project > Compute > Volumes > Volume Backups tab.

However, the Volume Backups tab is not enabled by default. To enable it, configure the dashboard accordingly:

By default, the Block Storage service uses the Object Storage service as a repository for backups. You can configure the Block Storage service to use an existing NFS share as a backup repository instead. To do so:

# crudini --set /etc/cinder/cinder.conf DEFAULT backup_file_size SIZE

# systemctl restart openstack-cinder-backup.service

Create a volume transfer from the dashboard

Accept a volume transfer from the dashboard

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.

To back up a volume, use the cinder backup-create command. By default, this command will create a full backup of the volume. If the volume has existing backups, you can choose to create an incremental backup instead (see Section 2.4.1.2, “Create an Incremental Volume Backup” for details.)

You can create backups of volumes you have access to. This means that users with administrative privileges can back up any volume, regardless of owner. For more information, see Section 2.4.1.1.1, “Create a Volume Backup as an Admin”.

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. For example,

+----------------+------------------------------------------+
|    Property    |                Value                     |
+----------------+------------------------------------------+
| backup_service |     cinder.backup.drivers.swift          |
|   backup_url   | eyJzdGF0dXMiOiAiYXZhaWxhYmxlIiwgIm9iam...|
|                | ...4NS02ZmY4MzBhZWYwNWUiLCAic2l6ZSI6IDF9 |
+----------------+------------------------------------------+

The volume backup metadata consists of the backup_service and backup_url values.

# cinder --os-auth-url KEYSTONEURL --os-tenant-name TENANTNAME --os-username USERNAME --os-password PASSWD backup-create VOLUME

By default, the cinder backup-create command will create a full backup of a volume. However, if the volume has existing backups, you can choose to create an incremental backup.

An incremental backup captures any changes to the volume since the last backup (full or incremental). Performing numerous, regular, full back ups of a volume can become resource-intensive as the volume’s size increases over time. In this regard, incremental backups allow you to capture periodic changes to volumes while minimizing resource usage.

To create an incremental volume backup, use the --incremental option. As in:

# cinder backup-create VOLUME --incremental

Replace VOLUME with the ID or Display Name of the volume you want to back up. Incremental backups are fully supported on NFS and Object Storage backup repositories.

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 service (openstack-cinder-backup). This metadata consists of backup_service and backup_url values, which you can export after creating the volume backup (as shown in Section 2.4.1.1, “Create a Full 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).

When migrating a volume between hosts, both hosts must reside on the same back end. Use the dashboard to perform the migration:

Migrating a volume between back ends, on the other hand, involves volume re-typing. This means that in order to migrate to a new back end:

See ] and xref:section-specify-backend[ for more details.

When defining the back end as an Extra Spec, use volume_backend_name as the Key. Its corresponding value will be the back end’s name, as defined in the Block Storage configuration file (/etc/cinder/cinder.conf). In this file, each back end is defined in its own section, and its corresponding name is set in the volume_backend_name parameter.

Once you have a back end defined in a target volume type, you can migrate a volume to that back end through re-typing. This involves re-applying the target volume type to a volume, thereby applying the new back end settings. See Section 2.3.10, “Changing a Volume’s Type (Volume Re-typing)” for instructions.

To do so: