doc: Document ceph-mgr module configuration options

Add comprehensive documentation for defining configuration options in
ceph-mgr modules, including all supported properties and their usage.

Previously, the documentation did not explain how to define ceph-mgr
module configuration options, despite subtle differences from other Ceph
components. This change documents all supported Option properties, their
types, and provides clear examples to help module developers properly
configure their options.

Signed-off-by: Kefu Chai <tchaikov@gmail.com>
(cherry picked from commit 121192f4c95df0ee282cecc7237c8ca788e9cfba)

diff --git a/doc/dev/config.rst b/doc/dev/config.rst
index 9cb20aee7e864fcfbb86f39311038674cd572c77..951dc6489cdb2af5970ee267ffcdbee4f5a9c2d2 100644 (file)
--- a/doc/dev/config.rst
+++ b/doc/dev/config.rst
@@ -96,6 +96,8 @@ the configuration. Just like with set_val, you should call apply_changes after
 calling these functions to make sure your changes get applied.
 
 
+.. _dev config defining options:
+
 Defining config options
 =======================
 
@@ -104,6 +106,13 @@ by their consumers. If an option is only used by ceph-osd, it should go to
 ``osd.yaml.in``. All the ``.yaml.in`` files are translated into ``.cc`` and ``.h`` files
 at build time by ``y2c.py``.
 
+.. note::
+   Ceph-mgr modules use the same configuration system as other Ceph components,
+   but their configuration options are defined within each module's Python
+   implementation. For details on defining mgr module configuration options,
+   see :ref:`mgr module dev configuration options`.
+
+
 Each option is represented using a YAML mapping (dictionary). A typical option looks like
 
 .. code-block:: yaml

diff --git a/doc/mgr/modules.rst b/doc/mgr/modules.rst
index 020d0ba7252910e7a25448e265ba78689fec3f63..4da8a2a9c0c462576a2c515df2d37f658a4e86d0 100644 (file)
--- a/doc/mgr/modules.rst
+++ b/doc/mgr/modules.rst
@@ -400,6 +400,7 @@ be automatically processed. Example:
 
 .. _`Rule of Silence`: http://www.linfo.org/rule_of_silence.html
 
+.. _mgr module dev configuration options:
 
 Configuration options
 ---------------------
@@ -412,15 +413,71 @@ Modules can load and store configuration options using the
    certificates). If you want to persist module-internal data or
    binary configuration data consider using the `KV store`_.
 
-You must declare your available configuration options in the
-``MODULE_OPTIONS`` class attribute, like this:
+Configuration options must be declared in the ``MODULE_OPTIONS`` class attribute:
 
 .. code-block:: python
 
     MODULE_OPTIONS = [
-        Option(name="my_option")
+        Option(name="check_interval",
+               level=OptionLevel.ADVANCED,
+               default=60,
+               type="secs",
+               desc="The interval in seconds to check the inbox",
+               long_desc="The interval in seconds to check the inbox. Set to 0 to disable the check",
+               min=0,
+               runtime=True)
     ]
 
+The example above demonstrates most supported properties, though typically only
+a subset is needed. The following properties are supported:
+
+**name**
+    The option's name. This is the only required property.
+
+**type** (optional, default: ``str``)
+    The option's data type. Supported types:
+
+    * ``uint`` - unsigned 64-bit integer
+    * ``int`` - signed 64-bit integer
+    * ``str`` - string
+    * ``float`` - double-precision floating point
+    * ``bool`` - boolean
+    * ``addr`` - Ceph messenger address for peer communication
+    * ``addrvec`` - comma-separated list of Ceph messenger addresses
+    * ``uuid`` - UUID as defined by `RFC 4122 <https://www.ietf.org/rfc/rfc4122.txt>`_
+    * ``size`` - size value (stored as uint64_t)
+    * ``secs`` - timespan in format ``"<number><unit>..."``, e.g., ``"3h 2m 1s"`` or ``"3weeks"``
+
+      Supported units: ``s``, ``sec``, ``second(s)``, ``m``, ``min``, ``minute(s)``,
+      ``h``, ``hr``, ``hour(s)``, ``d``, ``day(s)``, ``w``, ``wk``, ``week(s)``,
+      ``mo``, ``month(s)``, ``y``, ``yr``, ``year(s)``
+
+    * ``millisecs`` - timespan in milliseconds
+
+**desc**
+    Short description (can be a sentence fragment).
+
+**long_desc**
+    Detailed description using complete sentences or paragraphs.
+
+**default**
+    Default value for the option.
+
+**min** / **max**
+    Minimum and maximum allowed values.
+
+**enum_allowed**
+    For ``str`` type options, a list of allowed string values. Values outside this set are rejected.
+
+**see_also**
+    List of related option names (used in documentation only).
+
+**tags**
+    List of tags for categorizing the option (used in documentation only).
+
+**runtime** (default: ``False``)
+    Whether the option can be updated after module loading.
+
 If you try to use ``set_module_option`` or ``get_module_option`` on options
 not declared in ``MODULE_OPTIONS``, an exception will be raised.