Return all servers during multiple create¶
https://blueprints.launchpad.net/nova/+spec/return-all-servers-during-multiple-create
In this blueprint, we propose to improve the server create API in V3 by including all of the created servers in the response instead of only the first server. In V2, servers[0] is returned to the caller in response to a create request that has specified min/max_count.
Problem description¶
End users of the server create API have the ability to create multiple instances in one batch by specifying min/max_count in the request. One reason to use this ability is to scale up a cloud-hosted application quickly or in response to increased load. Upon requesting multiple servers, the user needs to know the list of servers that have been created in order to work with them. It would be ideal to receive the list in the response for the create request.
Proposed change¶
In order to provide the end user with the list of created servers most efficiently, we propose to change the server create API response in V3 from returning only one server to returning a list of servers. In the case when the end user has requested creation of just one server, a list containing one server will be returned.
Alternatives¶
Callers can work around in V2 by specifying return_reservation_id=True in the request to receive a reservation ID which they can use to obtain the list of servers. This is also currently possible in V3, but it requires an additional API call to get the server list.
Data model impact¶
None
REST API impact¶
V3 API specification:
Description: Create one or more servers
Method type: POST
Normal http response code: 202
Expected error http response codes:
400: Invalid request parameter, image/flavor not found
409: Port in use, no unique match
413: Quota or port limit exceeded
URL: v3/servers
Example JSON request (no change):
{ "server": { "name": "server-test-1", "image_ref": "b5660a6e-4b46-4be3-9707-6b47221b454f", "flavor_ref": "2", "max_count": 2, "min_count": 2 }Example JSON response (new format):
{ "servers": [ { "admin_password": "qpYU66rKxmnK", "id": "215d1109-216d-48c3-af8e-998bb9bc3ca0", "links": [ { "href": "http://openstack.example.com/v3/servers/<id>", "rel": "self" }, { "href": "http://openstack.example.com/servers/<id>", "rel": "bookmark" } ] }, { "admin_password": "wfksH3GTTseP", "id": "440cf918-3ee0-4143-b289-f63e1d2000e6", "links": [ { "href": "http://openstack.example.com/v3/servers/<id>", "rel": "self" }, { "href": "http://openstack.example.com/servers/<id>", "rel": "bookmark" } ] } ] }Partial JSON response schema definition to show change:
create = { 'type': 'object', 'properties': { 'servers': { 'type': 'array', 'items': { 'type': 'object', 'properties: { 'admin_password': {type': 'string'}, 'id': {'type': 'string'}, 'links': { 'type': 'array', 'items': { 'type': 'object', 'properties': { 'href': {'type': 'string'}, 'rel': {'type': 'string'} } } } } } } } }
Security impact¶
None
Notifications impact¶
None
Other end user impact¶
The python-novaclient will have to be changed to handle the list of servers in the V3 API server create response and show the list to the user.
Performance Impact¶
For a server create API request for multiple servers, instead of returning only the first server, all of the created server objects must be serialized and returned in the response instead of just the first one.
Other deployer impact¶
None
Developer impact¶
None
Implementation¶
Assignee(s)¶
- Primary assignee:
melwitt
- Other contributors:
None
Work Items¶
Change the V3 API response for server create to return a list of instances.
Update tests in tempest to handle the changed response.
Dependencies¶
This blueprint is related to the tasks API blueprint [1] because it needs to interact with how tasks will work in V3. Initial comments on this interaction are available in the original review [2].
[1] https://blueprints.launchpad.net/nova/+spec/instance-tasks-api
Testing¶
Tempest tests must be updated to accept the changed server create API response format. Tempest tests already exercise the various server creation scenarios, but the response format has changed for V3.
Documentation Impact¶
The changed REST API response for server create, as represented by the jsonschema definition above, will need to be documented. The changed API response will be available as API samples generated from testing.
References¶
None