Merge pull request ceph#62362 from phlogistonjohn/jjm-mgr-smb-tweaks

mgr/smb: additional input and output controls

Reviewed-by: Avan Thakkar <[email protected]>
Reviewed-by: Sachin Prabhu <[email protected]>

Author: adk3798

doc/mgr/smb.rst

@@ -55,7 +55,7 @@ Create Cluster
 
 .. code:: bash
 
-    $ ceph smb cluster create <cluster_id> {user|active-directory} [--domain-realm=<domain_realm>] [--domain-join-user-pass=<domain_join_user_pass>] [--define-user-pass=<define_user_pass>] [--custom-dns=<custom_dns>] [--placement=<placement>] [--clustering=<clustering>]
+    $ ceph smb cluster create <cluster_id> {user|active-directory} [--domain-realm=<domain_realm>] [--domain-join-user-pass=<domain_join_user_pass>] [--define-user-pass=<define_user_pass>] [--custom-dns=<custom_dns>] [--placement=<placement>] [--clustering=<clustering>] [--password-filter=<password_filter>] [--password-filter-out=<password_filter_out>]
 
 Create a new logical cluster, identified by the cluster id value. The cluster
 create command must specify the authentication mode the cluster will use. This
@@ -101,16 +101,40 @@ public_addrs
     Supported only when using Samba's clustering. Assign "virtual" IP
     addresses that will be managed by the clustering subsystem and may automatically
     move between nodes running Samba containers.
+password_filter
+    One of ``none`` or ``base64``. If the filter is ``none`` the password
+    values on the command line are assumed to be plain text. If the filter is
+    ``base64`` the password values are assumed to be obscured with
+    base64 encoding the string. If ``--password-filter-out`` is not specified
+    this filter will also be applied to the output.
+password_filter_out
+    One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the
+    password fields in the output are emitted as plain text. If the filter is
+    ``base64`` password fields will be obscured by base64 encoding the
+    string.  If the filter is ``hidden`` the password values will be replaced
+    by a invalid generic replacement string containing only asterisks.
 
 Remove Cluster
 ++++++++++++++
 
 .. code:: bash
 
-    $ ceph smb cluster rm <cluster_id>
+    $ ceph smb cluster rm <cluster_id> [--password-filter=<password_filter>]
 
 Remove a logical SMB cluster from the Ceph cluster.
 
+Options:
+
+cluster_id
+    A ``cluster_id`` value identifying a cluster resource.
+password_filter
+    One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the
+    password fields in the output are emitted as plain text. If the filter is
+    ``base64`` password fields will be obscured by base64 encoding the
+    string.  If the filter is ``hidden`` the password values will be replaced
+    by a invalid generic replacement string containing only asterisks.
+
+
 List Clusters
 ++++++++++++++
 
@@ -190,15 +214,68 @@ command, for example:
 
     $ ceph smb apply -i /path/to/resources.yaml
 
+In addition to the resource specification the ``apply`` sub-command accepts
+options that control how the input and output of the command behave:
+
+.. code:: bash
+
+    $ ceph smb apply [--format=<format>] [--password-filter=<password_filter>] [--password-filter-out=<password_filter_out>] -i <input>
+
+Options:
+
+format
+    One of ``json`` (the default) or ``yaml``. Output format can be
+    selected independent of the input format.
+password_filter
+    One of ``none`` or ``base64``. If the filter is ``none`` the password
+    fields in the input are assumed to be plain text. If the filter is
+    ``base64`` the password fields are assumed to be obscured with
+    base64 encoding the string. If ``--password-filter-out`` is not specified
+    this filter will also be applied to the output.
+password_filter_out
+    One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the
+    password fields in the output are emitted as plain text. If the filter is
+    ``base64`` password fields will be obscured by base64 encoding the
+    string.  If the filter is ``hidden`` the password values will be replaced
+    by a invalid generic replacement string containing only asterisks.
+input
+    A file name or ``-`` to use stdin.
+
+
 Resources that have already been applied to the Ceph cluster configuration can
 be viewed using the ``ceph smb show`` command. For example:
 
 .. code:: bash
 
-    $ ceph smb show [<resource_name>...]
+    $ ceph smb show ceph.smb.cluster.cluster1
+
+The ``show`` command can show all resources, resources of a given type, or specific
+resource items. Options can be provided that control the output of the command.
+
+.. code:: bash
+
+    $ ceph smb show [resource_name...] [--format=<format>] [--results=<results>] [--password-filter=<password_filter>]
+
+Options:
 
-The ``show`` command can show all resources of a given type or specific
-resources by id. ``resource_name`` arguments can take the following forms:
+resource_name
+    One or more strings specifying a resource or resource type. See description below.
+format
+    One of ``json`` (the default) or ``yaml``.
+results
+    One of ``collapsed`` (the default) or ``full``. When set to ``collapsed``
+    the output of the command will show only the resource JSON/YAML of
+    a single item if a single item is found. When set to ``full`` even if a
+    single item is found the output will always include a wrapper object like
+    (in pseudo-JSON): ``{"resources": [...Resource objects...]}``.
+password_filter
+    One of ``none``, ``base64``, or ``hidden``. If the filter is ``none`` the
+    password fields in the output are emitted as plain text. If the filter is
+    ``base64`` password fields will be obscured by base64 encoding the
+    string.  If the filter is ``hidden`` the password values will be replaced
+    by a invalid generic replacement string containing only asterisks.
+
+``resource_name`` arguments can take the following forms:
 
 - ``ceph.smb.cluster``: show all cluster resources
 - ``ceph.smb.cluster.<cluster_id>``: show specific cluster with given cluster id

src/pybind/mgr/smb/enums.py

@@ -102,3 +102,30 @@ class SMBClustering(_StrEnum):
     DEFAULT = 'default'
     ALWAYS = 'always'
     NEVER = 'never'
+
+
+class ShowResults(_StrEnum):
+    FULL = 'full'
+    COLLAPSED = 'collapsed'
+
+
+class PasswordFilter(_StrEnum):
+    """Filter type for password values."""
+
+    NONE = 'none'
+    BASE64 = 'base64'
+    HIDDEN = 'hidden'
+
+
+class InputPasswordFilter(_StrEnum):
+    """Filter type for input password values."""
+
+    NONE = 'none'
+    BASE64 = 'base64'
+
+    def to_password_filter(self) -> PasswordFilter:
+        """Convert input password filter to password filter type."""
+        # This is because python doesn't allow extending enums (with values)
+        # but we want a InputPasswordFilter to be a strict subset of the
+        # password filter enum.
+        return PasswordFilter(self.value)

src/pybind/mgr/smb/module.py

@@ -20,7 +20,10 @@
 )
 from .enums import (
     AuthMode,
+    InputPasswordFilter,
     JoinSourceType,
+    PasswordFilter,
+    ShowResults,
     SMBClustering,
     UserGroupSourceType,
 )
@@ -139,13 +142,49 @@ def internal_store_backend(self) -> str:
             self.get_module_option('internal_store_backend', ''),
         )
 
+    def _apply_res(
+        self,
+        resource_input: List[resources.SMBResource],
+        create_only: bool = False,
+        password_filter: InputPasswordFilter = InputPasswordFilter.NONE,
+        password_filter_out: Optional[PasswordFilter] = None,
+    ) -> results.ResultGroup:
+        in_pf = password_filter.to_password_filter()  # update enum type
+        # use the same filtering as the input unless expliclitly set
+        out_pf = password_filter_out if password_filter_out else in_pf
+        if in_pf is not PasswordFilter.NONE:
+            in_op = (in_pf, PasswordFilter.NONE)
+            log.debug('Password filtering for resource apply: %r', in_op)
+            resource_input = [r.convert(in_op) for r in resource_input]
+        all_results = self._handler.apply(
+            resource_input, create_only=create_only
+        )
+        if out_pf is not PasswordFilter.NONE:
+            # we need to apply the conversion filter to the output
+            # resources in the results - otherwise we would show raw
+            # passwords - this will be the inverse of the filter applied to
+            # the input
+            out_op = (PasswordFilter.NONE, out_pf)
+            log.debug('Password filtering for smb apply output: %r', in_op)
+            all_results = all_results.convert_results(out_op)
+        return all_results
+
     @cli.SMBCommand('apply', perm='rw')
-    def apply_resources(self, inbuf: str) -> results.ResultGroup:
+    def apply_resources(
+        self,
+        inbuf: str,
+        password_filter: InputPasswordFilter = InputPasswordFilter.NONE,
+        password_filter_out: Optional[PasswordFilter] = None,
+    ) -> results.ResultGroup:
         """Create, update, or remove smb configuration resources based on YAML
         or JSON specs
         """
         try:
-            return self._handler.apply(resources.load_text(inbuf))
+            return self._apply_res(
+                resources.load_text(inbuf),
+                password_filter=password_filter,
+                password_filter_out=password_filter_out,
+            )
         except resources.InvalidResourceError as err:
             # convert the exception into a result and return it as the only
             # item in the result group
@@ -172,6 +211,8 @@ def cluster_create(
         placement: Optional[str] = None,
         clustering: Optional[SMBClustering] = None,
         public_addrs: Optional[List[str]] = None,
+        password_filter: InputPasswordFilter = InputPasswordFilter.NONE,
+        password_filter_out: Optional[PasswordFilter] = None,
     ) -> results.Result:
         """Create an smb cluster"""
         domain_settings = None
@@ -282,13 +323,24 @@ def cluster_create(
             public_addrs=c_public_addrs,
         )
         to_apply.append(cluster)
-        return self._handler.apply(to_apply, create_only=True).squash(cluster)
+        return self._apply_res(
+            to_apply,
+            create_only=True,
+            password_filter=password_filter,
+            password_filter_out=password_filter_out,
+        ).squash(cluster)
 
     @cli.SMBCommand('cluster rm', perm='rw')
-    def cluster_rm(self, cluster_id: str) -> results.Result:
+    def cluster_rm(
+        self,
+        cluster_id: str,
+        password_filter: PasswordFilter = PasswordFilter.NONE,
+    ) -> results.Result:
         """Remove an smb cluster"""
         cluster = resources.RemovedCluster(cluster_id=cluster_id)
-        return self._handler.apply([cluster]).one()
+        return self._apply_res(
+            [cluster], password_filter_out=password_filter
+        ).one()
 
     @cli.SMBCommand('share ls', perm='r')
     def share_ls(self, cluster_id: str) -> List[str]:
@@ -324,18 +376,23 @@ def share_create(
                 subvolume=subvolume,
             ),
         )
-        return self._handler.apply([share], create_only=True).one()
+        return self._apply_res([share], create_only=True).one()
 
     @cli.SMBCommand('share rm', perm='rw')
     def share_rm(self, cluster_id: str, share_id: str) -> results.Result:
         """Remove an smb share"""
         share = resources.RemovedShare(
             cluster_id=cluster_id, share_id=share_id
         )
-        return self._handler.apply([share]).one()
+        return self._apply_res([share]).one()
 
-    @cli.SMBCommand('show', perm='r')
-    def show(self, resource_names: Optional[List[str]] = None) -> Simplified:
+    @cli.SMBCommand("show", perm="r")
+    def show(
+        self,
+        resource_names: Optional[List[str]] = None,
+        results: ShowResults = ShowResults.COLLAPSED,
+        password_filter: PasswordFilter = PasswordFilter.NONE,
+    ) -> Simplified:
         """Show resources fetched from the local config store based on resource
         type or resource type and id(s).
         """
@@ -346,9 +403,13 @@ def show(self, resource_names: Optional[List[str]] = None) -> Simplified:
                 resources = self._handler.matching_resources(resource_names)
             except handler.InvalidResourceMatch as err:
                 raise cli.InvalidInputValue(str(err)) from err
-        if len(resources) == 1:
+        if password_filter is not PasswordFilter.NONE:
+            op = (PasswordFilter.NONE, password_filter)
+            log.debug('Password filtering for smb show: %r', op)
+            resources = [r.convert(op) for r in resources]
+        if len(resources) == 1 and results is ShowResults.COLLAPSED:
             return resources[0].to_simplified()
-        return {'resources': [r.to_simplified() for r in resources]}
+        return {"resources": [r.to_simplified() for r in resources]}
 
     def submit_smb_spec(self, spec: SMBSpec) -> None:
         """Submit a new or updated smb spec object to ceph orchestration."""