Merge "The spec about adding extra_info field to the response of instances API"

doc/source/specs/instances-extra-info.rst

@@ -0,0 +1,200 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+===================================================
+Add extra_info field for the response of protectable instances API
+===================================================
+
+https://blueprints.launchpad.net/karbor/+spec/instances-extra-info
+
+Problem description
+===================
+We can only query the id, name and type of protectable instance using the restfull API
+of protectable instance. We can not get more info about the resource instance.
+Some other info about instance is also needed when we protect resources with different
+resources type.
+For example: database instance. only the name of database instance is not enough. The
+host ip, the database system name about the instance are also needed.
+
+
+Use Cases
+=========
+
+Scenario #1
+User want get the extra info of resource instances from the response of protectable
+instances API. Now the protectable instances API only return the id, name and type of
+the resource instances.
+
+Scenario #2
+User uses the Protectable Instances API to query the info of instances from the vendor's
+backup software. User also can save the extra_info of resource instances to the plan,
+not only the id, name, type of resources.
+
+
+
+
+Proposed change
+===============
+Protectable Instances API:
+When return a protectable instance, a new field would be available called
+``extra-info``.
+This field must be a dict in the format of::
+
+        {
+                "key1": "value1",
+                "key2": "value2",
+        }
+
+Keys and values *must* both be strings.
+The extra-info of instances is only used for presentation to a user/tenant.
+The values in extra-info filed of a resource can not be used inside the protection
+service of karbor and protection plugins.
+
+The UI about the extra-info of protectable instances
+Show the extra-info in resource tree page. Add a fa-chevron-right icon before the
+Logo of the resource. The extra-info of this resource is collapsed by default.
+If a user/tenant click the icon, The extra-info will be displayed under this resource.
+Click the icon again, the extra-info will be collapsed.
+
+Add a new field extra_info to the response for Protectable Instances API.
+  /{project_id}/protectables/{protectable_type}/instances:
+    get:
+      summary: Resource Instances
+      description: |
+        Return all the available instances for the given protectable type.
+          examples:
+            application/json: {
+              "instances": [
+                {
+                  "id": "cb4ef2ff-10f5-46c9-bce4-cf7a49c65a01",
+                  "type": "OS::Nova::Server",
+                  "name": "My VM",
+                  "extra_info": {
+                      "hostname": "KarborServer",
+                      "availability_zone": "AZOne",
+                      "cell_name": "CellOne"
+                    }
+                  "dependent_resources": [
+                    {
+                      "id": "99777fdd-8a5b-45ab-ba2c-52420008103f",
+                      "type": "OS::Glance::Image",
+                      "name": "cirros-0.3.4-x86_64-uec"
+                      "extra_info": {
+                          "availability_zone": "AZOne",
+                          "cell_name": "CellOne"
+                      }
+                    }
+                  ]
+                }
+              ]
+            }
+
+Protectable Plugins can return the extra_info of resource Instances.
+
+The extra_info field in resource database table is only for presentation to a user/tenant.
+The values in extra_info field can not be used and modified in karbor protection service.
+Add a new field extra_info to resources database table;
+ resources
++-------------------------+--------------+------+-----+---------+-------+
+| Field                   | Type         | Null | Key | Default | Extra |
++-------------------------+--------------+------+-----+---------+-------+
+| id                      | Integer      | NO   | PRI | NULL    |       |
+| plan_id                 | varchar(255) | NO   | FOR | NULL    |       |
+| resource_id             | varchar(36)  | NO   |     | NULL    |       |
+| resource_type           | varchar(64)  | NO   |     | NULL    |       |
+| resource_name           | varchar(255) | NO   |     | NULL    |       |
+| resource_extra_info     | Text         | NO   |     | NULL    |       |
+| created_at              | Datetime     | YES  |     | NULL    |       |
+| updated_at              | Datetime     | YES  |     | NULL    |       |
+| deleted_at              | Datetime     | YES  |     | NULL    |       |
+| deleted                 | Boolean      | NO   |     | NULL    |       |
++-------------------------+--------------+------+-----+---------+-------+
+
+
+
+Alternatives
+------------
+
+Do nothing, this is not a mission critical feature.
+
+Data model impact
+-----------------
+
+None
+
+REST API impact
+---------------
+
+Add a new field extra_info to the response for Protectable Instances API.
+
+Security impact
+---------------
+
+None
+
+Notifications impact
+--------------------
+
+None
+
+Other end user impact
+---------------------
+
+The new API will be exposed to users via the python-karborclient.
+
+Performance Impact
+------------------
+
+None
+
+Other deployer impact
+---------------------
+
+None
+
+Developer impact
+----------------
+
+None
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+
+Work Items
+----------
+
+* Write API
+* Add to Karbor client
+* Write tests
+* Add a usage example for API
+
+Dependencies
+============
+
+None
+
+
+Testing
+=======
+
+Unit tests in Karbor and the python-karborclient.
+
+
+Documentation Impact
+====================
+
+Add a usage example for API.
+
+
+References
+==========
+
+None