Add support for Block Storage API mv 3.60

sxmatch · ostackbrian · ostackbrian · commit 26a55de681c6 · 2020-04-06T10:19:39.000-04:00
Change I1f43c37c2266e43146637beadc027ccf6dec017e adds time-comparison
filtering to the volume list calls (summary and detail) in the Block
Storage API microversion 3.60.  The current cinderclient filter
support will pass these filters correctly, so the only change needed
on the client side is to bump the MAX_VERSION so that the client
can make calls to mv 3.60.

Co-authored-by: Brian Rosmaita &lt;rosmaita.fossdev@gmail.com&gt;
Change-Id: Ib4b7cbc7e527c0524336e139e127f19accfb7568
Partially-Implements: bp support-to-query-cinder-resources-filter-by-time-comparison-operators
diff --git a/cinderclient/api_versions.py b/cinderclient/api_versions.py
@@ -29,7 +29,7 @@
 # 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
@@ -149,6 +149,24 @@ def test_list_filters(self, resource, query_url):
              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
@@ -2749,24 +2749,66 @@ Lists all volumes.
 ``--tenant [<tenant>]``
   Display information from single tenant (Admin only).
 
+.. _cinder-list-filters-usage:
+
 ``--filters [<key=value> [<key=value> ...]]``
-  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
+  <https://docs.openstack.org/api-ref/block-storage/v3/index.html>`_ 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
@@ -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
+    <https://docs.openstack.org/python-cinderclient/latest/cli/details.html#cinder-list-filters-usage>`_
+    documentation for usage details.
