Jump to: navigation, search

Cinder Count API

Problem description

There is no current API that can retrieve summary count data for volumes that match a variety of search filters. For example, getting the total number of volumes in a given state or with certain metadata key/value pair(s). Retrieving all volumes and then manually determining the count data does not scale.

Use Case

A UI dashboard that contains volumes in various states. A new API is needed to retrieve the volume count data associated with various filters (ie, volumes in available state, volumes in error state, etc.)

Proposed change

The new count API will accept that same filter values as the existing /volumes API and re-use the existing filter processing (once the common parts are refactored into utility methods that can be utilized by both paths). However, instead of retrieving all of the volumes, only the number of matching volumes will be retrieved from the database and returned.

The new API will requires the following changes:

  • volume_get_count function in db\sqlalchemy\api.py that accepts a dict of filters (just like the existing volume_get_all function) and returns in integer. The query object will be constructed in the same manner (as in the volume_get_all function) to handle filter processing, but then the count() function will be invoked to return the integer count.
  • volume_get_count function in db\api.py that accepts a dict of filters and returns in integer
  • a get_count function on the API class in volume\api.py. The same filter processing done in the get_all function will be applied on the new function.
  • A new count API extension


Other APIs exist that return count data (quotas and limit) but they do not accept filter values.
I cannot think of alternative implementations. I believe that we want this new API to mimic the existing /volumes API in how the filters are processed into the database query object.

REST API impact

URL: v2/​{tenant_id}​/volumes/count

  • Description: Returns the number of Block Storage volumes that the tenant who submits the request can access that match the given search criteria (optional).
  • Method Type: GET
  • Normal http response code(s): 200
  • Expected error http response code(s): TBD, same as the existing /volumes API
  • Parameters: "all_tenants" will be used to signify that volumes from all tenants should be queried (admin only). Same filter values will be supported that the existing /volumes API supports.
  • JSON reply example: {"count": 5}

Other End user impact

python-cinderclient could be updated to expose this but it is not required.

Deployer impact


Developer impact



Assignee(s): Steven Kaufer
Other contributors: None


Targetted for: Juno
Originally approved for: Unknown
Completed: None

Work Items

  • Creating the new count functions in the volume\api.py layer, the new count functions in the database layers, and refactoring the common code (uses by the existing /servers API path) into utility methods that both paths will use
  • Exposing this function with an API extension




Unit testing to ensure that the correct count value is retrieved for various filters.

Documentation Impact

API documentation for new the API.