Add 'Restore Resources Status' spec

Protection plugin should be able to set the status of a restoring
resource during a restore operation. By doing so, users gain visiblity
of the restore process, the status of each resource, and the reason
for restore failure.

Change-Id: I5f08adce86a32306c8548fe32464d2863579c6ed
Implements: blueprint restore-resource-status

api-ref/source/v1/karbor-v1-restores.inc

@@ -68,6 +68,8 @@ Response
    - restore_target: restore_target
    - parameters: restore_parameters
    - status: restore_status
+   - resource_status: restore_resource_status
+   - resource_reason: restore_resource_reason
    - restores_links: links
 
 Response Example
@@ -130,6 +132,8 @@ Response
    - restore_auth: restore_auth
    - parameters: restore_parameters
    - status: restore_status
+   - resource_status: restore_resource_status
+   - resource_reason: restore_resource_reason
 
 Response Example
 ----------------
@@ -179,6 +183,8 @@ Response
    - restore_target: restore_target
    - parameters: restore_parameters
    - status: restore_status
+   - resource_status: restore_resource_status
+   - resource_reason: restore_resource_reason
 
 Response Example
 ----------------

api-ref/source/v1/parameters.yaml

@@ -353,6 +353,18 @@ restore_parameters:
   in: body
   required: true
   type: dict
+restore_resource_reason:
+  description: |
+    Map of the reason for failure of each resource in the restore
+  in: body
+  required: true
+  type: dict
+restore_resource_status:
+  description: |
+    Map of the restore status for each resource
+  in: body
+  required: true
+  type: dict
 restore_status:
   description: |
     The status of restore. A valid value is "``started``" "``success``" or

api-ref/source/v1/samples/restore-create-response.json

@@ -16,6 +16,12 @@
       "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": {
       }
     },
+    "resource_status": {
+      "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": "restoring",
+      "OS::Cinder::Volume#98eb847f-9f59-4d54-8b7b-5047bd2fa4c7": "restoring"
+    },
+    "resource_reason": {
+    },
     "status": "success"
   }
-}
+}

api-ref/source/v1/samples/restores-list-response.json

@@ -7,9 +7,23 @@
       "checkpoint_id": "dcb20606-ad71-40a3-80e4-ef0fafdad0c3",
       "restore_target": "http://192.168.1.2:35357/v2.0/",
       "parameters": {
+        "OS::Cinder::Volume": {
+        },
+        "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": {
+        }
+      },
+      "restore_auth": {
+        "type": "password",
         "username": "admin",
         "password": "***"
       },
+      "resource_status": {
+        "OS::Nova::Server#3f8af6c6-ecea-42bd-b44c-724785bbe5ea": "restoring",
+        "OS::Cinder::Volume#98eb847f-9f59-4d54-8b7b-5047bd2fa4c7": "error"
+      },
+      "resource_reason": {
+        "OS::Cinder::Volume#98eb847f-9f59-4d54-8b7b-5047bd2fa4c7": "Backup not found"
+      },
       "status": "success"
     }
   ],
@@ -19,4 +33,4 @@
       "rel": "next"
     }
   ]
-}
+}

doc/source/specs/restore-resource-status.rst

@@ -0,0 +1,96 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=======================
+Restore Resource Status
+=======================
+
+https://blueprints.launchpad.net/karbor/+spec/restore-resource-status
+
+Protection plugin should be able to set the status of a restoring resource
+during a restore operation. By doing so, users gain visiblity of the restore
+process:
+
+- Resources currently being protected
+- Resources restored successfully
+- Resources whose restore has failed, and the reason for the failure
+
+
+Problem description
+===================
+
+Use Cases
+---------
+
+- Giving visibility for the restore process
+- Exposing the user to the reason for the failure of a resource restore
+
+Proposed Change
+===============
+
+- Add 'resource_status' and 'resource_reason' dictionaries to the Restore object
+- Add 'update_resource_status' method to the Restore object
+- Protection Plugin should use the 'update_resource_status' to set the status of
+  each resource during restore operation
+
+
+Alternatives
+------------
+
+By not adding this, users will have no visibility to resource status during and
+after restore operation.
+
+Data model impact
+-----------------
+
+- Add 'resource_status' dictionary to Restore object: represents the status of
+  the restoring/restored resource
+- Add 'resource_reason' dictionary to Restore object: free text representing the
+  reason for the restore failure of the resource
+
+REST API impact
+---------------
+
+- 'resource_status' dictionary and 'resource_reason' dictionary are added to the
+  Restore object
+
+Security impact
+---------------
+
+Validation should be imposed on the status set by plugins, and on the reason
+text.
+
+Other end user impact
+---------------------
+
+python-karborclient and karbor-dashboard should consume the new fields of the
+Restore object.
+
+Performance Impact
+------------------
+
+Calling 'update_resource_status' sets values in the database which should have
+a slight impact on performance.
+
+
+Other deployer impact
+---------------------
+
+Protection plugins should use the new API to set the resource status.
+
+Implementation
+==============
+
+
+Testing
+=======
+
+
+Documentation Impact
+====================
+
+- Add 'resource_status' and 'resource_reason' to Restore object
+- Add 'update_restore_status' to Protection Plugin writing documentation