Merge "Add blueprint for support-reset-state-for-backup"

specs/juno/support-reset-state-for-backup.rst

@@ -0,0 +1,155 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+======================
+Backup State Reset API
+======================
+
+Include the URL of your launchpad blueprint:
+
+https://blueprints.launchpad.net/cinder/+spec/support-reset-state-for-backup
+
+Provide an API to to reset the state of a backup being stucked in creating or
+restoring.
+
+Problem description
+===================
+
+Since there are volume reset-state function and snapshot reset-state function,
+backup also needs reset-state as well.
+When creating or restoring backup, it may leave backup stucked in creating or
+restoring status due to database down or rabbitmq down, etc..
+Currently we could only solve these problems by restarting cinder-backup. This
+bp is to another mean for administrators to solve these problems by calling
+backup reset state API.
+
+1. Resetting status from creating/restoring to available
+1) restoring --> available
+Directly change the backup status to 'error', because the backup data is
+already existed in storage backend.
+2) creating --> available
+Use backup-create routine as an example to illustrate what benefit we can get
+from backup-reset function. Backup-create routine first backup volume and
+metadatas, and then update the status of volume and backup. If database just
+went down after update the volume's status to 'available', leaving the
+backup's status to be 'creating' without having methods to deal with through
+API.
+If we have reset-state API and resetting status from creating to available, we
+first verify whether the backup is ok on storage backend.
+If so, we change backup status from creating to available.
+If not, we throw an exception and change backup status from creating to error.
+
+2. Resetting status from creating/restoring to error
+Directly change the backup status to 'error' without restart cinder-backup.
+
+Proposed change
+===============
+
+A new API function and corresponding cinder command will be added to reset
+the status of backups.
+
+The initial proposal is to provide a method for administrator to handle the
+backup item stucked in status like creating or restoring.
+
+Alternatives
+------------
+
+Login in the cinder database, use the following update sql to change the
+backup item.
+    update backups set status='some status' where id='xxx-xxx-xxx-xxx';
+
+Data model impact
+-----------------
+None
+
+REST API impact
+---------------
+
+Add a new REST API to reset backup states:
+  * POST /v2/{tenant_id}/backups/{id}/action
+
+JSON request schema definition::
+
+    'backup-reset_status': {
+        'status': 'available'
+    }
+
+Normal http response code:
+    202
+
+Expected error http response code:
+    400
+
+Security impact
+---------------
+None
+
+Notifications impact
+--------------------
+None
+
+Other end user impact
+---------------------
+
+A new command, backup-reset-state, will be added to python-cinderclient. This
+command mirrors the underlying API function.
+
+Resetting the status of a backup can be performed by:
+$ cinder backup-reset-state --state <state> <backup>
+
+
+Performance Impact
+------------------
+None
+
+Other deployer impact
+---------------------
+None
+
+Developer impact
+----------------
+None
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  ling-yun
+
+Work Items
+----------
+
+* Implement REST API
+* Implement cinder client functions
+* Implement cinder command
+
+Dependencies
+============
+None
+
+Testing
+=======
+None
+
+
+Documentation Impact
+====================
+
+The cinder client documentation will need to be updated to reflect the new
+command.
+
+The cinder API documentation will need to be updated to reflect the REST API
+changes.
+
+
+References
+==========
+
+None