diff --git a/specs/wallaby/sizing-encrypted-volumes.rst b/specs/wallaby/sizing-encrypted-volumes.rst new file mode 100644 index 00000000..9ffa78d9 --- /dev/null +++ b/specs/wallaby/sizing-encrypted-volumes.rst @@ -0,0 +1,195 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +======================== +Sizing encrypted volumes +======================== + +https://blueprints.launchpad.net/cinder/+spec/sizing-encrypted-volumes + +Problem description +=================== + +If you have an unencrypted volume and migrate to an encrypted type, it fails +because there isn't enough space on the target to fit the entire source +volume. This happens because an encrypted volume must have a header, which +takes up some space. + +In fact, the exact amount of space lost isn't clear, it may vary by +LUKSv1/LUKSv2 and PLAIN dm-crypt formats. It's probably on the order of 1-2 +MB, but we allocate space in GB. Whether you can do really fine-grained space +allocation or not probably depends on the backend containing the volume. +However, we also need to keep the gigabyte boundaries for accounting purposes +(usage, quotas, charges, etc.) because that's what everyone's tooling expects. + +In addition, drivers optimize migration in different ways, and since we +previously didn't have a new size parameter, there's no easy way to get this +info into the drivers. + +Taking everything into consideration, we could have a flag indicating that +it's OK for the volume to be increased in size if it's required for the +retype to succeed. This way we don't go behind the user's back -- we fail if +the volume won't fit, and allow them to retype to a new size if they want the +retype to succeed. + +Use Cases +========= + +The main use-case here is when upgrading an old deployment and would like to +encrypt old volumes after that. + +Proposed change +=============== + +* The manager.py will create a destination volume bigger + GB size if the flag ‘allow-resize==on_demand’ and the destination volume-type + is encrypted. + +* Driver-specific method ‘_copy_volume_data’ for copy volume data when using block + devices (i.e LVM will still use the actual _migrate_volume_generic). This method + will be called after _before_volume_copy during volume migration. + +* RPC minor version for a new param + 3.x - Add allow_resize to retype method and increase_size to migrate method. + +* Add a new optional field, "allow_resize", to the os-retype action. Possible + values will be "on-demand" or "never" (which are the same as the current + "migration_policy" field). If not specified, the default is "never". + +* Add a new optional field, "increase_size", to the os-migrate action. The + operator specifies how many GB to grow the volume (so the final size is current + size + increase_size). + +* Add the next parameters to Python-cinderclient for retype and migrate commands: + + - Retype: New flag ``--allow-resize`` indicating that it's OK for the volume to be + increased in size if it's required for the retype to succeed. + + .. code-block:: bash + + Optional Arguments: + --allow-resize + Allow the volume to be increased in size during the retype if the system + decides it is necessary. This argument is recommended when retyping to + an encryption type. + ... + + - Migration: allow a new size to be specified during a volume migration. New + optional argument added ``--increase-size'`` + + .. code-block:: bash + + Optional Arguments: + --increase-size [] Number of GiBs to grow the volume during migration. + This is recommended when migrating to an encrypted host. + ... + +* The displayed size of the volume will be the actual size of the volume. + +Alternatives +------------ + +Leave everything as it is and don’t allow this kind of migration. To help users +add some workaround to the documentation (i.e. backup the volume and then restore +the volume to a bigger one). <1GB size increases won't be allowed, as explained +in the problem description above. + +Data model impact +----------------- + +None + +REST API impact +--------------- + +* Microversion bump + +* New parameters should be passed to retype and migrate commands as explained in + the ‘proposed change’ section. + +Security impact +--------------- + +None. If you're allowed to migrate at all, you should be able to increase the size, +and if you're allowed to retype, you should be able to allow-resize. + +Notifications impact +-------------------- + +None + +Other end user impact +--------------------- + +None + +Performance Impact +------------------ + +None + +Other deployer impact +--------------------- + +None + +Developer impact +---------------- + +None + + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + Sofia Enriquez + +Work Items +---------- + +* Implement new logic in cinder +* Implement new logic in python-cinderclient +* Unit-tests +* Tempest tests + +Dependencies +============ + +None + + +Testing +======= + +Unit tests and current devstack-based jobs won’t be enough to test these +changes. At least two tests should be added to +cinder_tempest_plugin/api/volume/admin/test_volume_retype.py + +1. retype unencrypted volume to LUKS type. +2. retype encrypted LUKS volume to regular type. + +Documentation Impact +==================== + +Currently I’ve added some documentation notes warning about retyping an +unencrypted/encrypted volume. However, these notes should be replaced with +proper documentation. + +Notes to be removed +- https://review.opendev.org/#/c/732988/ +- https://review.opendev.org/#/c/745199/ + + +References +========== + +* https://etherpad.opendev.org/p/sizing-encrypted-volumes +* Victoria Mid Cycle https://wiki.openstack.org/wiki/CinderVictoriaMidCycleSummary +* Victoria PTG https://wiki.openstack.org/wiki/CinderVictoriaPTGSummary#Sizing_encrypted_volumes