From a39a36c345e52aab5284d322cf6c945543e633eb Mon Sep 17 00:00:00 2001 From: chenying Date: Mon, 17 Oct 2016 17:36:44 +0800 Subject: [PATCH] The spec about adding extra_info field to the response of instances API Add a spec about the protectable instances API. User can get the extra_info of resource instances from the response of this API. blueprint instances-extra-info Change-Id: I41c8aeadad9a75744c3b01ef9536c942cf97ef49 --- doc/source/specs/instances-extra-info.rst | 200 ++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 doc/source/specs/instances-extra-info.rst diff --git a/doc/source/specs/instances-extra-info.rst b/doc/source/specs/instances-extra-info.rst new file mode 100644 index 00000000..d4a5c5ad --- /dev/null +++ b/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