Merge "add 'show-server-group' spec"

specs/stein/approved/show-server-group.rst

@@ -0,0 +1,164 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==================================================
+show which server group a server is in "nova show"
+==================================================
+
+bp link:
+
+https://blueprints.launchpad.net/nova/+spec/show-server-group
+
+Problem description
+===================
+
+Currently you had to loop over all groups to find the group the server
+belongs to. This spec tries to address this by proposing showing the server
+group information in API `GET /servers/{server_id}`.
+
+Use Cases
+---------
+
+* Admin/End user want to know the server group that the server belongs to
+  in a direct way.
+
+
+Proposed change
+===============
+
+Proposes to add the server-group UUID to ``GET /servers/{id}``,
+``PUT /servers/{server_id}`` and REBUILD API
+``POST /servers/{server_id}/action``.
+
+The server-group information will not be included in
+``GET /servers/detail`` API, because the server-group information
+needs another DB query.
+
+
+Alternatives
+------------
+
+*  One alternative is support the server groups filter by server UUID. Like
+  "GET /os-server-groups?server=<UUID>".
+
+* Another alternative to support the server group query is following API:
+  "GET /servers/{server_id}/server_groups".
+
+Data model impact
+-----------------
+
+NO
+
+
+REST API impact
+---------------
+
+
+Allows the `GET /servers/{server_id}` API to show server group's UUID.
+"PUT /servers/{server_id}" and REBUILD API "POST /servers/{server_id}/action"
+also response same information.
+
+.. highlight:: json
+
+The returned information for server group::
+
+    {
+        "server": {
+            "server_groups": [ # not cached
+                   "0b5d2c72-12cc-4ba6-a8d7-3ff5cc1d8cb8"
+            ]
+        }
+    }
+
+
+
+Security impact
+---------------
+
+N/A
+
+Notifications impact
+--------------------
+
+N/A
+
+Other end user impact
+---------------------
+
+* python novaclient would contain the server_group information.
+
+Performance Impact
+------------------
+
+* Need another DB query retrieve the server group UUID. To reduce the
+  perfermance impact for batch API call, "GET /servers/detail" won't
+  return server group information.
+
+Other deployer impact
+---------------------
+
+N/A
+
+Developer impact
+----------------
+
+N/A
+
+Upgrade impact
+--------------
+
+N/A
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  Yongli He
+
+
+Work Items
+----------
+
+* Add new microversion for this change.
+
+
+Dependencies
+============
+
+N/A
+
+Testing
+=======
+
+* Add functional api_sample tests.
+* Add microversion releated test to tempest.
+
+Documentation Impact
+====================
+
+* The API document should be changed to introduce this new feature.
+
+References
+==========
+
+* Stein PTG discussion:https://etherpad.openstack.org/p/nova-ptg-stein
+
+
+History
+=======
+
+.. list-table:: Revisions
+   :header-rows: 1
+
+   * - Release Name
+     - Version
+
+   * - Stein
+     - First Version
+