diff --git a/specs/queens/update-backup-size-when-backup-is-created.rst b/specs/queens/update-backup-size-when-backup-is-created.rst new file mode 100644 index 00000000..5a118c0b --- /dev/null +++ b/specs/queens/update-backup-size-when-backup-is-created.rst @@ -0,0 +1,188 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +=========================================== +Update backup's size when backup is created +=========================================== + +https://blueprints.launchpad.net/cinder/+spec/report-size-when-backup-created + +This blueprint proposes to update backup with the size reported by +backup backend when backup is created. + +Problem description +=================== + +Most clouds provide end user a convenient way to protect their data by +creating a backup for their volume. Users can create any backup copy at +anytime, and the cloud providers charge them by the backup size in total. +As the basic volume service, Cinder supports creating, restoring and +deleting backups plus the backup quotas, but our backup size isn't correct +at present, the backup's size always equals to the original volume's size +even if the incremental backup doesn't have any content in it. + +Use Cases +========= + +Backup's size attribute will reflect the actual size on the backend, the quota +and charge would be more accurate. + +Proposed change +=============== + +This spec proposes that the backup driver should report the actual size that +object holds at the backend when backup is created. So, when user requests to +create a backup for a volume with 10G, Cinder will still generate the record +with 10G as well as consume 10G for quota reservation, but when the actual +size is reported, we will update both the object and the quotas. + +**Note**: The actual size here stands for the final size at the backend, that +means if we create backup for a 1G volume which only has 200mb data and +after compression only 100mb is used at disk, the actual size is 100mb, +not 200mb or 1G. + +As Cinder has the unified unit G for every resource, that size should be +rounded up to G too, for example, if we create an incremental backup whose +actual size is only 12mb at backend, driver should still report 1 G to +Cinder service: + +.. code-block:: python + + def backup(self, backup, volume_file, backup_metadata=False): + """Start a backup of a specified volume. + + Driver should return the size that the backup object holds + in the backend, with the unit of G. For instance: + + .. code-block:: python + + { + 'size': 2 + } + """ + return + +Cinder's backup service would use this ``size`` to update backup model +as well as commit portion of the reservation (Instead of commit the +reservation record, Cinder will update the reservation and then commit +the updated record after backup is actually created in the background +to cover this case ). + +In order to report the actual size that backup holds, drivers need +to record or calculate the object size. Take our ``chunkeddriver`` for +instance, the total size is accumulated by the objects' size:: + + size = object1_size + object2_size.... + +If compression feature is enabled, the object's size should be:: + + size = compressed_object1_size + compressed_object2_size... + +Now Cinder has the attribute ``size`` for backup object which +only reflects the volume's size when created. In order to support +updating the actual size of the backup, we will add one more attribute +here. + +1. **volume_size**: This is used to record the original volume's size +and can be used to create new volume when restoring, we can not directly +link to the original volume size here because we could resize the volume +after the volume is backed up. + +2. **size**: This will be used to store the reported value from driver +rather the original volume size. And when backup is first created, +this value would be equal to the ``volume_size`` and will be updated +when backup is created at backend. + + +Alternatives +------------ + +Keep using volume's size to generate the backup's size as well as quota +usage record in database. + +Data model impact +----------------- + +None + +REST API impact +--------------- + +None + +Cinder-client impact +-------------------- + +None + +Security impact +--------------- + +None + +Notifications impact +-------------------- + +None + +Other end user impact +--------------------- + +None + +Performance Impact +------------------ + +There would be a slight performance impact +when committing quota reservations. + +Other deployer impact +--------------------- + +None + +Developer impact +---------------- + +Developer should report backup's size in ``backup`` method +when adding new backup driver. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + tommylikehu(tommylikehu@gmail.com) + +Work Items +---------- + +* Update cinder to support update the backup size. +* Update existing driver to report backup's actual size. +* Add related unit testcases. + +Dependencies +============ + +None + +Testing +======= + +* Add unit tests to cover this change. + +Documentation Impact +==================== + +* Update the base backup driver's interface. +* Update developer's documentation to advertise this change. + +References +========== + +None