9.5 KiB
Add pagination and changes-since filter support for os-migrations API
https://blueprints.launchpad.net/nova/+spec/add-pagination-and-change-since-for-migration-list
This blueprint adds limit and marker optional parameters to GET /os-migrations request to support pagination.
This blueprint also adds changes-since optional parameter to GET /os-migrations request to support filtering response data by last updated time.
Problem description
Currently, os-migrations API does not support pagination. As in large scale deployment the number of migration records can be also very large and querying them all can lead to performance bottleneck, it will be very useful to support pagination.
Also, os-migrations API does not support filtering the migration record by last updated time. As for production deployment, the system will be up for a very long time, and the number of migration records will also be very big. It will be very useful to support filter by last updated time.
Use Cases
For large scale production deployment, the administrator can use pagination and last updated time filter to have more efficient database query.
Proposed change
Add an API microversion that allows to get several migrations using general pagination mechanism with the help of limit and marker optional parameters to GET /os-migrations request. And add filter with the help of changes-since optional parameter to GET /os-migrations request.
- marker: The last migration UUID of the previous page. Displays list of migrations after "marker".
- limit: Maximum number of migrations to display. If limit is bigger than [api]/max_limit option of Nova API, limit [api]/max_limit will be used instead.
For multiple cells, we could have migrations with same ID, the migration ID as pagination marker won't work. Currently, the migration record has a uuid column on it, we just need add the migration UUID field in the response, and the migration UUID needs to be the pagination marker.
We propose to merge sort the results in compute api code once we get the results back from all of the multiple cells, and results are sorted in descending order by ['created_at', 'id'] keys.
Alternatives
None
Data model impact
A database index will be added on migrations.updated_at to improve the performance of filtering migrations by 'changes-since' parameter.
REST API impact
The proposal would add API microversion for getting several migrations using general pagination mechanism. New optional parameters limit, marker, and changes-since will be added to GET /os-migrations request.
Generic request format :
GET /os-migrations?limit={limit}&marker={migration_uuid}
Get all migrations :
GET /os-migrations
Response :
{ "migrations": [ { "created_at": "2012-10-29T13:42:02.000000", "dest_compute": "compute2", "dest_host": "1.2.3.4", "dest_node": "node2", "id": 1, "instance_uuid": "instance_id_123", "new_instance_type_id": 2, "old_instance_type_id": 1, "source_compute": "compute1", "source_node": "node1", "status": "Done", "updated_at": "2012-10-29T13:42:02.000000", "uuid": "12341d4b-346a-40d0-83c6-5f4f6892b650" }, { "created_at": "2013-10-22T13:42:02.000000", "dest_compute": "compute20", "dest_host": "5.6.7.8", "dest_node": "node20", "id": 2, "instance_uuid": "instance_id_456", "new_instance_type_id": 6, "old_instance_type_id": 5, "source_compute": "compute10", "source_node": "node10", "status": "Done", "updated_at": "2013-10-22T13:42:02.000000", "uuid": "56781d4b-346a-40d0-83c6-5f4f6892b650" }, { "created_at": "2013-10-22T13:45:02.000000", "dest_compute": "compute21", "dest_host": "5.6.7.8", "dest_node": "node21", "id": 3, "instance_uuid": "instance_id_4561", "new_instance_type_id": 6, "old_instance_type_id": 5, "source_compute": "compute10", "source_node": "node10", "status": "Done", "updated_at": "2013-10-22T13:45:02.000000", "uuid": "56791d4b-346a-40d0-83c6-5f4f6892b650" } ] }
Get no more than 2 migrations :
GET /os-migrations?limit=2
Response :
{ "migrations": [ { "created_at": "2012-10-29T13:42:02.000000", "dest_compute": "compute2", "dest_host": "1.2.3.4", "dest_node": "node2", "id": 1, "instance_uuid": "instance_id_123", "new_instance_type_id": 2, "old_instance_type_id": 1, "source_compute": "compute1", "source_node": "node1", "status": "Done", "updated_at": "2012-10-29T13:42:02.000000", "uuid": "12341d4b-346a-40d0-83c6-5f4f6892b650" }, { "created_at": "2013-10-22T13:42:02.000000", "dest_compute": "compute20", "dest_host": "5.6.7.8", "dest_node": "node20", "id": 2, "instance_uuid": "instance_id_456", "new_instance_type_id": 6, "old_instance_type_id": 5, "source_compute": "compute10", "source_node": "node10", "status": "Done", "updated_at": "2013-10-22T13:42:02.000000", "uuid": "56781d4b-346a-40d0-83c6-5f4f6892b650" } ], "migrations_links": [ { "href": "https://openstack.example.com/v2.1/os-migrations?limit=2&marker=56781d4b-346a-40d0-83c6-5f4f6892b650", "rel": "next" } ] }
Get all migrations after uuid=12341d4b-346a-40d0-83c6-5f4f6892b650 :
GET /os-migrations?marker=12341d4b-346a-40d0-83c6-5f4f6892b650
Response :
{ "migrations": [ { "created_at": "2013-10-22T13:42:02.000000", "dest_compute": "compute20", "dest_host": "5.6.7.8", "dest_node": "node20", "id": 2, "instance_uuid": "instance_id_456", "new_instance_type_id": 6, "old_instance_type_id": 5, "source_compute": "compute10", "source_node": "node10", "status": "Done", "updated_at": "2013-10-22T13:42:02.000000", "uuid": "56781d4b-346a-40d0-83c6-5f4f6892b650" }, { "created_at": "2013-10-22T13:45:02.000000", "dest_compute": "compute21", "dest_host": "5.6.7.8", "dest_node": "node21", "id": 3, "instance_uuid": "instance_id_4561", "new_instance_type_id": 6, "old_instance_type_id": 5, "source_compute": "compute10", "source_node": "node10", "status": "Done", "updated_at": "2013-10-22T13:45:02.000000", "uuid": "56791d4b-346a-40d0-83c6-5f4f6892b650" } ] }
Get all migrations after changes-since=2013-10-22T13:45:02.000000 :
GET /os-migrations?changes-since=2013-10-22T13:45:02.000000
Note
The provided time should be an ISO 8061 formatted time. ex 2013-10-22T13:45:02.000000, 2017-10-18T16:06:59Z
Response :
{
"migrations":[
{
"created_at": "2013-10-22T13:45:02.000000",
"dest_compute": "compute21",
"dest_host": "5.6.7.8",
"dest_node": "node21",
"id": 3,
"instance_uuid": "instance_id_4561",
"new_instance_type_id": 6,
"old_instance_type_id": 5,
"source_compute": "compute10",
"source_node": "node10",
"status": "Done",
"updated_at": "2013-10-22T13:45:02.000000",
"uuid": "56791d4b-346a-40d0-83c6-5f4f6892b650"
}
]
}
Security impact
None
Notifications impact
None
Other end user impact
Python-novaclient will be modified to handle the new microversion for migration pagination support.
Performance Impact
None
Other deployer impact
None
Developer impact
None
Implementation
Assignee(s)
- Primary assignee:
-
Yikun Jiang
- Other contributors:
-
Zhenyu Zheng
Work Items
- Create a new API microversion for getting several migrations using general pagination mechanism and time stamp filtering and adding a migration UUID field in the response.
- Modify the Nova client to handle the new microversion for migration pagination support.
Dependencies
None
Testing
Would need new in-tree functional and unit tests.
Documentation Impact
Docs needed for new API microversion and usage.
References
History
Release Name | Description |
---|---|
Newton | Proposed |
Queens | Re-proposed |