Merge "Add support for Block Storage API mv 3.60"

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 = {}

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',

doc/source/cli/details.rst

@@ -2744,24 +2744,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:
 

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.