doc/mgr: document new external ceph cluster support for smb

Document the new feature that allows smb clusters on one Ceph cluster to
make use of CephFS running on a different external Ceph cluster.

Signed-off-by: John Mulligan <jmulligan@redhat.com>

diff --git a/doc/mgr/smb.rst b/doc/mgr/smb.rst
index 526a6ac42c47c4b3cdadf72ee0fdd023ba7e64f6..f7acc0bb58140b3af938f93cf0083bf2a161bcc7 100644 (file)
--- a/doc/mgr/smb.rst
+++ b/doc/mgr/smb.rst
@@ -618,6 +618,10 @@ remote_control
     ca_cert
         Optional object. The fields are described in :ref:`tls source
         fields<tls-source-fields>`
+external_ceph_cluster:
+    Optional object. The fields are described in :ref:`external Ceph cluster
+    source fields<external-ceph-cluster-source-fields>`. This is an
+    advanced option and should be used with caution.
 custom_smb_global_options
     Optional mapping. Specify key-value pairs that will be directly added to
     the global ``smb.conf`` options (or equivalent) of a Samba server.  Do
@@ -684,6 +688,17 @@ ref
     String. Required for ``source_type: resource``. Must refer to the ID of a
     ``ceph.smb.tls.credential`` resource
 
+
+.. _external-ceph-cluster-source-fields:
+
+An external Ceph cluster source object supports the following fields:
+
+source_type:
+    Optional. Must be ``resource`` if specified.
+ref:
+    String. Required for ``source_type: resource``. Must refer to the ID of
+    a ``ceph.smb.ext.cluster`` resource
+
 .. note::
    The ``source_type`` ``empty`` is generally only for debugging and testing
    the module and should not be needed in production deployments.
@@ -990,6 +1005,47 @@ Example:
       -----END CERTIFICATE-----
 
 
+External Ceph Cluster Resource
+------------------------------
+
+This resource can be used to configure an SMB Cluster hosted on Ceph cluster to
+use CephFS volumes provided by an external Ceph cluster.  The values provided
+below allow the SMB server to connect to a cluster other than the one it is
+running on.
+
+.. warning::
+   This is an advanced feature that should be used with care. It allows
+   SMB servers to contact CephFS on a different cluster. Because of that, many
+   values provided below can not be validated and other validations that smb
+   mgr module normally does are disabled.
+   In addition, automatic subvolume to path mapping is disabled. Shares in SMB
+   clusters making use of an external Ceph cluster *must* not specify a
+   subvolume by name and *must* specify an absolute path to a subvolume.
+
+An external ceph cluster resource supports the following fields.
+
+resource_type
+    A literal string ``ceph.smb.ext.cluster``
+external_ceph_cluster_id
+    A short string identifying the cluster
+intent
+    One of ``present`` or ``removed``. If not provided, ``present`` is
+    assumed. If ``removed`` all following fields are optional
+fsid
+    String. The UUID/FSID of the external cluster
+mon_host
+    String. The ``mon_host`` string (as sourced from a ceph.conf file)
+cephfs_user
+    Object. Fields:
+
+    name
+        String. A ceph user name indicating the cephx user that will
+        access the CephFS volume(s) on the external cluster
+    key
+        String. The Base64 encoded key value corresponding to the cephx
+        user name provided
+
+
 A Declarative Configuration Example
 -----------------------------------