Chapter 4. Performing advanced operations with the Block Storage service (cinder) Block Storage volumes form persistent storage for Compute instances in your overcloud. Configure advanced features of your volumes, for example, using volume snapshots, migrating volumes, retyping volumes, and configuring multipath. 4.1. Creating, using, and deleting volume snapshots You can preserve the state of a volume at a specific point in time by creating a volume snapshot. You can then use the snapshot to clone new volumes. 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. You cannot delete a volume if it has existing snapshots. Volume backups prevent data loss, whereas snapshots facilitate cloning. For this reason, snapshot back ends are typically colocated with volume back ends to minimize latency during cloning. By contrast, a backup repository is usually located in a different location, for example, on a different node, physical storage, or even geographical location in a typical enterprise deployment. This is to protect the backup repository from any damage that might occur to the volume back end. For more information about volume backups, see the Block Storage Backup Guide . Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Access to the Red Hat OpenStack Platform (RHOSP) Dashboard (horizon). For more information, see Overcloud deployment output . Procedure In the dashboard, select Project > Compute > Volumes . Select the target volume's Create Snapshot action. 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 when 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 3.1, "Creating Block Storage volumes" . Important If you want to create a new volume from a snapshot of an encrypted volume, ensure that the new volume is at least 1GB larger than the old 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.10, "Protected and unprotected snapshots in a Red Hat Ceph Storage back end" for more information about snapshot security and troubleshooting. Note For RADOS block device (RBD) volumes for the Block Storage service (cinder) that are created from snapshots, you can use the CinderRbdFlattenVolumeFromSnapshot heat parameter to flatten and remove the dependency on the snapshot. When you set CinderRbdFlattenVolumeFromSnapshot to true , the Block Storage service flattens RBD volumes and removes the dependency on the snapshot and also flattens all future snapshots. The default value is false, which is also the default value for the cinder RBD driver. Be aware that flattening a snapshot removes any potential block sharing with the parent and results in larger snapshot sizes on the back end and increases the time for snapshot creation. 4.2. Restoring a volume from a snapshot You can recover the most recent snapshot of a volume. This means that you can perform an in-place revert of the volume data to its most recent snapshot. Warning The ability to recover the most recent snapshot of a volume is supported but is driver dependent. The correct implementation of this feature is driver assisted. For more information about support for this feature, contact your driver vendor. Limitations There might be limitations to using the revert-to-snapshot feature with multi-attach volumes. Check whether such limitations apply before you use this feature. You cannot revert a volume that you resize (extend) after you take a snapshot. You cannot use the revert-to-snapshot feature on an attached or in-use volume. Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Access to the Red Hat OpenStack Platform (RHOSP) Dashboard (horizon). For more information, see Overcloud deployment output . Block Storage (cinder) API microversion 3.40 or later. You must have created at least one snapshot for the volume. Procedure Log in to the undercloud as the stack user. Source the overcloudrc file: Detach your volume: Replace <instance_id> and <vol_id> with the IDs of the instance and volume that you want to revert. Locate the ID or name of the snapshot that you want to revert. You can only revert the latest snapshot. Revert the snapshot: Replace <snapshot_id or snapshot_name> with the ID or the name of the snapshot. Optional: You can use the cinder snapshot-list command to check that the volume you are reverting is in a reverting state. Reattach the volume: Replace <instance_id> and <vol_id> with the IDs of the instance and volume that you reverted. Verification To check that the procedure is successful, you can use the cinder list command to verify that the volume you reverted is now in the available state. Note If you used Block Storage (cinder) as a bootable root volume, you cannot use the revert-to-snapshot feature on that volume because it is not in the available state. To use this feature, the instance must have been booted with the delete_on_termination=false (default) property to preserve the boot volume if the instance is terminated. When you want to revert to a snapshot, you must first delete the initial instance so that the volume is available. You can then revert it and create a new instance from the volume. 4.3. Uploading a volume to the Image service (glance) You can upload an existing volume as an image to the Image service directly. Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Access to the Red Hat OpenStack Platform (RHOSP) Dashboard (horizon). For more information, see Overcloud deployment output . Procedure In the dashboard, select Project > Compute > Volumes . Select the target volume's Upload to Image action. Provide an Image Name for the volume and select a Disk Format from the list. Click Upload . 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 Image service in the Creating and Managing Images guide. 4.4. Moving volumes between back ends There are many reasons to move volumes from one storage back end to another, such as: To retire storage systems that are no longer supported. To change the storage class or tier of a volume. To change the availability zone of a volume. With the Block Storage service (cinder), you can move volumes between back ends in the following ways: Retype: The default policy allows volume owners and administrators to retype a volume. The retype operation is the most common way to move volumes between back ends. Migrate: The default policy allows only administrators to migrate a volume. Volume migration is reserved for specific use cases, because it is restrictive and requires a clear understanding about how deployments work. For more information, see Section 4.8, "Migrating a volume between back ends with the CLI" . Restrictions Red Hat supports moving volumes between back ends within and across availability zones (AZs), but with the following restrictions: Volumes must have either available or in-use status to move. Support for in-use volumes is driver dependent. Volumes cannot have snapshots. Volumes cannot belong to a group or consistency group. 4.4.1. Moving available volumes You can move available volumes between all back ends, but performance depends on the back ends that you use. Many back ends support assisted migration. For more information about back-end support for assisted migration, contact the vendor. Assisted migration works with both volume retype and volume migration. With assisted migration, the back end optimizes the movement of the data from the source back end to the destination back end, but both back ends must be from the same vendor. Note Red Hat supports back-end assisted migrations only with multi-pool back ends or when you use the cinder migrate operation for single-pool back ends, such as RBD. When assisted migrations between back ends are not possible, the Block Storage service performs a generic volume migration. Generic volume migration requires volumes on both back ends to be connected before the Block Storage (cinder) service moves data from the source volume to the Controller node and from the Controller node to the destination volume. The Block Storage service seamlessly performs the process regardless of the type of storage from the source and destination back ends. Important Ensure that you have adequate bandwidth before you perform a generic volume migration. The duration of a generic volume migration is directly proportional to the size of the volume, which makes the operation slower than assisted migration. 4.4.2. Moving in-use volumes There is no optimized or assisted option for moving in-use volumes. When you move in-use volumes, the Compute service (nova) must use the hypervisor to transfer data from a volume in the source back end to a volume in the destination back end. This requires coordination with the hypervisor that runs the instance where the volume is in use. The Block Storage service (cinder) and the Compute service work together to perform this operation. The Compute service manages most of the work, because the data is copied from one volume to another through the Compute node. Important Ensure that you have adequate bandwidth before you move in-use volumes. The duration of this operation is directly proportional to the size of the volume, which makes the operation slower than assisted migration. Restrictions In-use multi-attach volumes cannot be moved while they are attached to more than one nova instance. Non block devices are not supported, which limits storage protocols on the target back end to be iSCSI, Fibre Channel (FC), and RBD. 4.5. Block Storage volume retyping Volume retyping is the standard way to move volumes from one back end to another. The operation requires the administrator to define the appropriate volume types for the different back ends. The default policy allows volume owners and administrators to retype volumes. When you retype a volume, you apply a volume type and its settings to an already existing volume. For more information about volume types, see Section 2.3, "Group volume configuration with volume types" . You can retype a volume provided that the extra specs of the new volume type can be applied to the existing volume. You can retype a volume to apply pre-defined settings or storage attributes to an existing volume, such as: To move the volume to a different back end. To change the storage class or tier of a volume. To enable or disable features such as replication. Retyping a volume does not necessarily mean that you must move the volume from one back end to another. However, there are circumstances in which you must move a volume to complete a retype: The new volume type has a different volume_backend_name defined. The volume_backend_name of the current volume type is undefined, and the volume is stored in a different back end than the one specified by the volume_backend_name of the new volume type. Moving a volume from one back end to another can require extensive time and resources. Therefore, when a retype requires moving data, the Block Storage service does not move data by default. The operation fails unless it is explicitly allowed by specifying a migration policy as part of the retype request. For more information, see Section 4.5.2, "Retyping a volume from the command line" . Restrictions You cannot retype all volumes. For more information about moving volumes between back ends, see Section 4.4, "Moving volumes between back ends" . Unencrypted volumes cannot be retyped to encrypted volume types, but encrypted volumes can be retyped to unencrypted ones. Retyping an unencrypted volume to an encrypted volume of the same size is not supported, because encrypted volumes require additional space to store encryption data. For more information about encrypting unencrypted volumes, see Encrypting unencrypted volumes . Users with no administrative privileges can only retype volumes that they own. 4.5.1. Retyping a volume from the dashboard UI Use the dashboard UI to retype a volume. Important Retyping an unencrypted volume to an encrypted volume of the same size is not supported, because encrypted volumes require additional space to store encryption data. For more information about encrypting unencrypted volumes, see Encrypting unencrypted volumes . Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Access to the Red Hat OpenStack Platform (RHOSP) Dashboard (horizon). For more information, see Overcloud deployment output . Procedure In the dashboard, select Project > Compute > Volumes . In the Actions column of the volume you want to migrate, select Change Volume Type . In the Change Volume Type dialog, select the target volume type and define the new back end from the Type list. If you are migrating the volume to another back end, select On Demand from the Migration Policy list. For more information, see Section 4.4, "Moving volumes between back ends" . Click Change Volume Type to start the migration. 4.5.2. Retyping a volume from the command line Similar to the dashboard UI procedure, you can retype a volume from the command line. Important Retyping an unencrypted volume to an encrypted volume of the same size is not supported, because encrypted volumes require additional space to store encryption data. For more information about encrypting unencrypted volumes, see Encrypting unencrypted volumes . Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Procedure Enter the following command to retype a volume: If the retype operation requires moving the volume from one back end to another, the Block Storage service requires a specific flag: 4.6. Attach a volume to multiple instances Volume multi-attach gives multiple instances simultaneous read/write access to a Block Storage volume. The Ceph RBD driver is supported. Warning You must use a multi-attach or cluster-aware file system to manage write operations from multiple instances. Failure to do so causes data corruption. Limitations of multi-attach volumes The Block Storage (cinder) back end must support multi-attach volumes. For information about supported back ends, contact Red Hat Support. Your Block Storage (cinder) driver must support multi-attach volumes. Contact Red Hat support to verify that multi-attach is supported for your vendor plugin. For more information about the certification for your vendor plugin, see the following locations: https://access.redhat.com/articles/1535373#Cinder https://access.redhat.com/ecosystem/search/#/category/Software?sort=sortTitle%20asc&softwareCategories=Storage&ecosystem=Red%20Hat%20OpenStack%20Platform Read-only multi-attach volumes are not supported. Live migration of multi-attach volumes is not available. Encryption of multi-attach volumes is not supported. Multi-attach volumes are not supported by the Bare Metal Provisioning service (ironic) virt driver. Multi-attach volumes are supported only by the libvirt virt driver. You cannot retype an attached volume from a multi-attach type to a non-multi-attach type, and you cannot retype a non-multi-attach type to a multi-attach type. You cannot use multi-attach volumes that have multiple read write attachments as the source or destination volume during an attached volume migration. You cannot attach multi-attach volumes to shelved offloaded instances. Simultaneous API calls, such as create or resize, to instances attached to the same multi-attach volume can fail. For more information, see https://access.redhat.com/solutions/7077470 . 4.6.1. Creating a multi-attach volume type To attach a volume to multiple instances, set the multiattach flag to <is> True in the volume extra specs. When you create a multi-attach volume type, the volume inherits the flag and becomes a multi-attach volume. Note By default, creating a new volume type is an admin-only operation. Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Procedure Run the following commands to create a multi-attach volume type: Note This procedure creates a volume on any back end that supports multiattach. Therefore, if there are two back ends that support multiattach, the scheduler decides which back end to use based on the available space at the time of creation. Run the following command to specify the back end: 4.6.2. Multi-attach volume retyping You can retype a volume to be multi-attach capable or retype a multi-attach capable volume to make it incapable of attaching to multiple instances. However, you can retype a volume only when it is not in use and its status is available . When you attach a multi-attach volume, some hypervisors require special considerations, such as when you disable caching. Currently, there is no way to safely update an attached volume while keeping it attached the entire time. Retyping fails if you attempt to retype a volume that is attached to multiple instances. 4.6.3. Creating a multi-attach volume After you create a multi-attach volume type, create a multi-attach volume. Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Procedure Run the following command to create a multi-attach volume: Run the following command to verify that a volume is multi-attach capable. If the volume is multi-attach capable, the multiattach field equals True . steps Attaching a volume to an instance 4.7. Migrating a volume between back ends with the Dashboard With the Block Storage service (cinder) you can migrate volumes between back ends within and across availability zones (AZs). This is the least common way to move volumes from one back end to another. The default policy allows only administrators to migrate volumes. Do not change the default policy. In highly customized deployments or in situations in which you must retire a storage system, an administrator can migrate volumes. In both use cases, multiple storage systems share the same volume_backend_name , or it is undefined. Restrictions The volume cannot be replicated. The destination back end must be different from the current back end of the volume. The existing volume type must be valid for the new back end, which means the following must be true: Volume type must not have the backend_volume_name defined in its extra specs, or both Block Storage back ends must be configured with the same backend_volume_name . Both back ends must support the same features configured in the volume type, such as support for thin provisioning, support for thick provisioning, or other feature configurations. Note Moving volumes from one back end to another might require extensive time and resources. For more information, see Section 4.4, "Moving volumes between back ends" . Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . A successful overcloud deployment. For more information, see Creating a basic overcloud with CLI tools . Access to the Red Hat OpenStack Platform (RHOSP) Dashboard (horizon). For more information, see Overcloud deployment output . Procedure In the dashboard, select Admin > Volumes . In the Actions column of the volume you want to migrate, select Migrate Volume . In the Migrate Volume dialog, select the target host from the Destination Host drop-down list. Note To bypass any driver optimizations for the host migration, select the Force Host Copy check box. Click Migrate to start the migration. 4.8. Migrating a volume between back ends with the CLI With the Block Storage service (cinder) you can migrate volumes between back ends within and across availability zones (AZs). This is the least common way to move volumes from one back end to another. The default policy allows only administrators to migrate volumes. Do not change the default policy. In highly customized deployments or in situations in which you must retire a storage system, an administrator can migrate volumes. In both use cases, multiple storage systems share the same volume_backend_name , or it is undefined. Restrictions The volume cannot be replicated. The destination back end must be different from the current back end of the volume. The existing volume type must be valid for the new back end, which means the following must be true: Volume type must not have the backend_volume_name defined in its extra specs, or both Block Storage back ends must be configured with the same backend_volume_name . Both back ends must support the same features configured in the volume type, such as support for thin provisioning, support for thick provisioning, or other feature configurations. Note Moving volumes from one back end to another might require extensive time and resources. For more information, see Section 4.4, "Moving volumes between back ends" . Prerequisites A successful undercloud installation. For more information, see Installing director on the undercloud . Procedure Enter the following command to retrieve the name of the destination back end: The back end names take the form host@volume_backend_name#pool . In the example output, there are two LVM back ends exposed in the Block Storage service: localdomain@lvmdriver-1#lvmdriver-1 and localdomain@lvmdriver-2#lvmdriver-1 . Notice that both back ends share the same volume_backend_name , lvmdriver-1 . Enter the following command to migrate a volume from one back end to another: 4.9. Encrypting unencrypted volumes To encrypt an unencrypted volume, you must either back up the unencrypted volume and then restore it to a new encrypted volume, or create a glance image from the unencrypted volume and then create a new encrypted volume from the image. Prerequisites An unencrypted volume that you want to encrypt. Procedure If the cinder-backup service is available, back up the current unencrypted volume: Replace <unencrypted_volume> with the name or ID of the unencrypted volume. Create a new encrypted volume: Replace <encrypted_volume_size> with the size of the new volume in GB. This value must be larger than the size of the unencrypted volume by 1GB to accommodate the encryption metadata. Replace <encrypted_volume_type> with the encryption type that you require. Restore the backup of the unencrypted volume to the new encrypted volume: Replace <backup> with the name or ID of the unencrypted volume backup. Replace <encrypted_volume> with the ID of the new encrypted volume. If the cinder-backup service is unavailable, use the upload-to-image command to create an image of the unencrypted volume, and then create a new encrypted volume from the image. Create a glance image of the unencrypted volume: Replace <unencrypted_volume> with the name or ID of the unencrypted volume. Replace <new_image> with a name for the new image. Create a new volume from the image that is 1GB larger than the image: Replace <size> with the size of the new volume. This value must be 1GB larger than the size of the old unencrypted volume. Replace <new_image> with the name of the image that you created from the unencrypted volume. Replace <encrypted_volume_name> with a name for the new encrypted volume. 4.10. Protected and unprotected snapshots in a Red Hat Ceph Storage back end When you use Red Hat Ceph Storage (RHCS) as a back end for your Red Hat OpenStack Platform (RHOSP) deployment, you can set a snapshot to protected in the back end. Do not delete protected snapshots through the RHOSP dashboard or the cinder snapshot-delete command because deletion fails. When this occurs, set the snapshot to unprotected in the RHCS back end first. You can then delete the snapshot through RHOSP as normal. Additional resources For more information about protecting snapshots, see Protecting a block device snapshot and Unprotecting a block device snapshot .

Commands:
[stack@undercloud ~] USD source overcloudrc
nova volume-detach <instance_id> <vol_id>
cinder snapshot-list
cinder --os-volume-api-version=3.40 revert-to-snapshot <snapshot_id or snapshot_name>
cinder snapshot-list
nova volume-attach <instance_id> <vol_id>
cinder list
cinder retype <volume name or id> <new volume type name>
cinder retype --migration-policy on-demand <volume name or id> <new volume type name>
cinder type-create multiattach cinder type-key multiattach set multiattach="<is> True"
cinder type-key multiattach set volume_backend_name=<backend_name>
cinder create <volume_size> --name <volume_name> --volume-type multiattach
cinder show <vol_id> | grep multiattach | multiattach | True |
cinder get-pools --detail Property | Value | name | localdomain@lvmdriver-1#lvmdriver-1 | pool_name | lvmdriver-1 | volume_backend_name | lvmdriver-1 Property | Value | | name | localdomain@lvmdriver-2#lvmdriver-1 | pool_name | lvmdriver-1 | volume_backend_name | lvmdriver-1
cinder migrate <volume id or name> <new host>
cinder backup-create <unencrypted_volume>
cinder create <encrypted_volume_size> --volume-type <encrypted_volume_type>
cinder backup-restore <backup> --volume <encrypted_volume>
cinder upload-to-image <unencrypted_volume> <new_image>
cinder volume create --size <size> --volume-type luks --image <new_image> <encrypted_volume_name>