diff --git a/cinderclient/api_versions.py b/cinderclient/api_versions.py index 54d2fceca..2d2219953 100644 --- a/cinderclient/api_versions.py +++ b/cinderclient/api_versions.py @@ -29,7 +29,7 @@ LOG = logging.getLogger(__name__) # key is a deprecated version and value is an alternative version. DEPRECATED_VERSIONS = {"2": "3"} DEPRECATED_VERSION = "2.0" -MAX_VERSION = "3.59" +MAX_VERSION = "3.60" MIN_VERSION = "3.0" _SUBSTITUTIONS = {} diff --git a/cinderclient/tests/unit/v3/test_shell.py b/cinderclient/tests/unit/v3/test_shell.py index 06c3d443a..6a2523802 100644 --- a/cinderclient/tests/unit/v3/test_shell.py +++ b/cinderclient/tests/unit/v3/test_shell.py @@ -149,6 +149,24 @@ class ShellTest(utils.TestCase): u'list --filters name=abc --filters size=1', 'expected': '/volumes/detail?name=abc&size=1'}, + {'command': + u'list --filters created_at=lt:2020-01-15T00:00:00', + 'expected': + '/volumes/detail?created_at=lt%3A2020-01-15T00%3A00%3A00'}, + {'command': + u'list --filters updated_at=gte:2020-02-01T00:00:00,' + u'lt:2020-03-01T00:00:00', + 'expected': + '/volumes/detail?updated_at=gte%3A2020-02-01T00%3A00%3A00%2C' + 'lt%3A2020-03-01T00%3A00%3A00'}, + {'command': + u'list --filters updated_at=gte:2020-02-01T00:00:00,' + u'lt:2020-03-01T00:00:00 --filters created_at=' + u'lt:2020-01-15T00:00:00', + 'expected': + '/volumes/detail?created_at=lt%3A2020-01-15T00%3A00%3A00' + '&updated_at=gte%3A2020-02-01T00%3A00%3A00%2C' + 'lt%3A2020-03-01T00%3A00%3A00'}, # testcases for list group {'command': 'group-list --filters name=456', diff --git a/doc/source/cli/details.rst b/doc/source/cli/details.rst index e182fa5b6..c377ac987 100644 --- a/doc/source/cli/details.rst +++ b/doc/source/cli/details.rst @@ -2744,24 +2744,66 @@ Lists all volumes. ``--tenant []`` Display information from single tenant (Admin only). +.. _cinder-list-filters-usage: + ``--filters [ [ ...]]`` - Filter - key - and - value - pairs. - Please - use - 'cinder - list-filters' - to - check - enabled - filters - from - server, - Default=None. (Supported by API version 3.33 and - later) + Filter key and value pairs. + Please use the ``cinder list-filters`` command to check enabled filters + from server. + Default=None. + (Supported by API version 3.33 and later) + + **Time Comparison Filters** + + Beginning with API version 3.60, you can apply time comparison filtering + to the ``created_at`` and ``updated at`` fields. Time must be + expressed in ISO 8601 format: CCYY-MM-DDThh:mm:ss±hh:mm. The + ±hh:mm value, if included, returns the time zone as an offset from + UTC. + + To use time comparison filtering, use the standard ``key=value`` syntax + for the ``--filters`` option. The allowable keys are: + + * ``created_at`` + * ``updated_at`` + + The value is a *time comparison statement*, which is specified as follows: + a comparison operator, followed immediately by a colon (``:``), followed + immediately by a time expressed in ISO 8601 format. You can filter by a + *time range* by appending a comma (``,``) followed a second time + comparison statement. + + Six *comparison operators* are supported: + + * ``gt`` (greater than) - return results more recent than the specified + time + * ``gte`` (greater than or equal) - return any results matching the + specified time and also any more recent results + * ``eq`` (equal) - return any results matching the specified time + exactly + * ``neq`` (not equal) - return any results that do not match the + specified time + * ``lt`` (less than) - return results older than the specified time + * ``lte`` (less than or equal) - return any results matching the + specified time and also any older results + + **Examples** + + To filter the response to volumes created before 15 January 2020: + + .. code-block:: console + + cinder list --filters created_at=lt:2020-01-15T00:00:00 + + To filter the response to those volumes updated in February 2020: + + .. code-block:: console + + cinder list --filters updated_at=gte:2020-02-01T00:00:00,lt:2020-03-01T00:00:00 + + See the `Block Storage API v3 Reference + `_ for + more information. .. _cinder_list-extensions: diff --git a/releasenotes/notes/support-bs-mv-3.60-a65f1919b5068d17.yaml b/releasenotes/notes/support-bs-mv-3.60-a65f1919b5068d17.yaml new file mode 100644 index 000000000..3813767c3 --- /dev/null +++ b/releasenotes/notes/support-bs-mv-3.60-a65f1919b5068d17.yaml @@ -0,0 +1,13 @@ +--- +features: + - | + When communicating with the Block Storage API version 3.60 and higher, + you can apply time comparison filtering to the volume list command + on the ``created_at`` or ``updated_at`` fields. Time must be + expressed in ISO 8601 format: CCYY-MM-DDThh:mm:ss±hh:mm. The + ±hh:mm value, if included, returns the time zone as an offset from + UTC. + + See the `Block Storage service (cinder) command-line client + `_ + documentation for usage details.