Add volume summary command

This patch adds the ``volume summary`` command which shows the total
size, total count and metadata of all volumes.
This command is available from microversion 3.12 and the metadata
info is available from microversion 3.36.

Change-Id: I6472337e8b1dc91aad5fbe416673a5d5a5d5fa88

6 files changed, 215 insertions, 1 deletions

diff --git a/doc/source/cli/command-objects/volume.rst b/doc/source/cli/command-objects/volume.rst
index ac414110..5bfa547a 100644
--- a/doc/source/cli/command-objects/volume.rst
+++ b/doc/source/cli/command-objects/volume.rst
@@ -388,3 +388,8 @@ Unset volume properties
 .. describe:: <volume>
 
     Volume to modify (name or ID)
+
+Block Storage v3
+
+ .. autoprogram-cliff:: openstack.volume.v3
+     :command: volume summary
diff --git a/doc/source/cli/data/cinder.csv b/doc/source/cli/data/cinder.csv
index 8b25d3fd..9b0f7636 100644
--- a/doc/source/cli/data/cinder.csv
+++ b/doc/source/cli/data/cinder.csv
@@ -120,7 +120,7 @@ snapshot-rename,snapshot set --name,Renames a snapshot.
 snapshot-reset-state,snapshot set --state,Explicitly updates the snapshot state.
 snapshot-show,snapshot show,Shows snapshot details.
 snapshot-unmanage,volume snapshot delete --remote,Stop managing a snapshot.
-summary,,Get volumes summary. (Supported by API versions 3.12 - 3.latest)
+summary,volume summary,Get volumes summary. (Supported by API versions 3.12 - 3.latest)
 thaw-host,volume host set --enable,Thaw and enable the specified cinder-volume host.
 transfer-accept,volume transfer accept,Accepts a volume transfer.
 transfer-create,volume transfer create,Creates a volume transfer.
diff --git a/openstackclient/tests/unit/volume/v3/test_volume.py b/openstackclient/tests/unit/volume/v3/test_volume.py
new file mode 100644
index 00000000..783f0852
--- /dev/null
+++ b/openstackclient/tests/unit/volume/v3/test_volume.py
@@ -0,0 +1,121 @@
+#
+#   Licensed under the Apache License, Version 2.0 (the "License"); you may
+#   not use this file except in compliance with the License. You may obtain
+#   a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#   License for the specific language governing permissions and limitations
+#   under the License.
+#
+
+import copy
+
+from cinderclient import api_versions
+from osc_lib.cli import format_columns
+from osc_lib import exceptions
+
+from openstackclient.tests.unit.volume.v2 import fakes as volume_fakes
+from openstackclient.volume.v3 import volume
+
+
+class TestVolumeSummary(volume_fakes.TestVolume):
+
+    columns = [
+        'Total Count',
+        'Total Size',
+    ]
+
+    def setUp(self):
+        super().setUp()
+
+        self.volumes_mock = self.app.client_manager.volume.volumes
+        self.volumes_mock.reset_mock()
+        self.mock_vol_1 = volume_fakes.create_one_volume()
+        self.mock_vol_2 = volume_fakes.create_one_volume()
+        self.return_dict = {
+            'volume-summary': {
+                'total_count': 2,
+                'total_size': self.mock_vol_1.size + self.mock_vol_2.size}}
+        self.volumes_mock.summary.return_value = self.return_dict
+
+        # Get the command object to test
+        self.cmd = volume.VolumeSummary(self.app, None)
+
+    def test_volume_summary(self):
+        self.app.client_manager.volume.api_version = \
+            api_versions.APIVersion('3.12')
+        arglist = [
+            '--all-projects',
+        ]
+        verifylist = [
+            ('all_projects', True),
+        ]
+        parsed_args = self.check_parser(self.cmd, arglist, verifylist)
+
+        columns, data = self.cmd.take_action(parsed_args)
+
+        self.volumes_mock.summary.assert_called_once_with(
+            all_tenants=True,
+        )
+
+        self.assertEqual(self.columns, columns)
+
+        datalist = (
+            2,
+            self.mock_vol_1.size + self.mock_vol_2.size)
+        self.assertCountEqual(datalist, tuple(data))
+
+    def test_volume_summary_pre_312(self):
+        arglist = [
+            '--all-projects',
+        ]
+        verifylist = [
+            ('all_projects', True),
+        ]
+        parsed_args = self.check_parser(self.cmd, arglist, verifylist)
+
+        exc = self.assertRaises(
+            exceptions.CommandError,
+            self.cmd.take_action,
+            parsed_args)
+        self.assertIn(
+            '--os-volume-api-version 3.12 or greater is required',
+            str(exc))
+
+    def test_volume_summary_with_metadata(self):
+        self.app.client_manager.volume.api_version = \
+            api_versions.APIVersion('3.36')
+
+        combine_meta = {**self.mock_vol_1.metadata, **self.mock_vol_2.metadata}
+        meta_dict = copy.deepcopy(self.return_dict)
+        meta_dict['volume-summary']['metadata'] = combine_meta
+        self.volumes_mock.summary.return_value = meta_dict
+
+        new_cols = copy.deepcopy(self.columns)
+        new_cols.extend(['Metadata'])
+
+        arglist = [
+            '--all-projects',
+        ]
+        verifylist = [
+            ('all_projects', True),
+        ]
+        parsed_args = self.check_parser(self.cmd, arglist, verifylist)
+
+        columns, data = self.cmd.take_action(parsed_args)
+
+        self.volumes_mock.summary.assert_called_once_with(
+            all_tenants=True,
+        )
+
+        self.assertEqual(new_cols, columns)
+
+        datalist = (
+            2,
+            self.mock_vol_1.size + self.mock_vol_2.size,
+            format_columns.DictColumn(combine_meta))
+        self.assertCountEqual(datalist, tuple(data))
diff --git a/openstackclient/volume/v3/volume.py b/openstackclient/volume/v3/volume.py
new file mode 100644
index 00000000..07bd434f
--- /dev/null
+++ b/openstackclient/volume/v3/volume.py
@@ -0,0 +1,81 @@
+#
+#   Licensed under the Apache License, Version 2.0 (the "License"); you may
+#   not use this file except in compliance with the License. You may obtain
+#   a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#   License for the specific language governing permissions and limitations
+#   under the License.
+#
+
+"""Volume V3 Volume action implementations"""
+
+import logging
+
+from cinderclient import api_versions
+from osc_lib.cli import format_columns
+from osc_lib.command import command
+from osc_lib import exceptions
+from osc_lib import utils
+
+from openstackclient.i18n import _
+
+
+LOG = logging.getLogger(__name__)
+
+
+class VolumeSummary(command.ShowOne):
+    _description = _("Show a summary of all volumes in this deployment.")
+
+    def get_parser(self, prog_name):
+        parser = super().get_parser(prog_name)
+        parser.add_argument(
+            '--all-projects',
+            action='store_true',
+            default=False,
+            help=_('Include all projects (admin only)'),
+        )
+        return parser
+
+    def take_action(self, parsed_args):
+
+        volume_client = self.app.client_manager.volume
+
+        if volume_client.api_version < api_versions.APIVersion('3.12'):
+            msg = _(
+                "--os-volume-api-version 3.12 or greater is required to "
+                "support the 'volume summary' command"
+            )
+            raise exceptions.CommandError(msg)
+
+        columns = [
+            'total_count',
+            'total_size',
+        ]
+        column_headers = [
+            'Total Count',
+            'Total Size',
+        ]
+        if volume_client.api_version.matches('3.36'):
+            columns.append('metadata')
+            column_headers.append('Metadata')
+
+        # set value of 'all_tenants' when using project option
+        all_projects = parsed_args.all_projects
+
+        vol_summary = volume_client.volumes.summary(
+            all_tenants=all_projects,
+        )
+
+        return (
+            column_headers,
+            utils.get_dict_properties(
+                vol_summary['volume-summary'],
+                columns,
+                formatters={'metadata': format_columns.DictColumn},
+            ),
+        )
diff --git a/releasenotes/notes/add-volume-summary-command-b2175b48af3ccab1.yaml b/releasenotes/notes/add-volume-summary-command-b2175b48af3ccab1.yaml
new file mode 100644
index 00000000..1c5cdf18
--- /dev/null
+++ b/releasenotes/notes/add-volume-summary-command-b2175b48af3ccab1.yaml
@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Added ``volume summary`` command to show the total size,
+    total count and metadata of volumes.
diff --git a/setup.cfg b/setup.cfg
index 42ce970b..c8c7a8a4 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -811,3 +811,5 @@ openstack.volume.v3 =
     volume_transfer_request_delete = openstackclient.volume.v2.volume_transfer_request:DeleteTransferRequest
     volume_transfer_request_list = openstackclient.volume.v2.volume_transfer_request:ListTransferRequest
     volume_transfer_request_show = openstackclient.volume.v2.volume_transfer_request:ShowTransferRequest
+
+    volume_summary = openstackclient.volume.v3.volume:VolumeSummary