From 868ae0201606b093b8eaaf7623f8b450f9e340e3 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Wed, 25 Jun 2025 10:26:58 +0800 Subject: [PATCH] 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 (cherry picked from commit 121192f4c95df0ee282cecc7237c8ca788e9cfba) --- doc/dev/config.rst | 9 +++++++ doc/mgr/modules.rst | 63 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 69 insertions(+), 3 deletions(-) diff --git a/doc/dev/config.rst b/doc/dev/config.rst index 9cb20aee7e864..951dc6489cdb2 100644 --- 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 020d0ba725291..4da8a2a9c0c46 100644 --- 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 `_ + * ``size`` - size value (stored as uint64_t) + * ``secs`` - timespan in format ``"..."``, 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. -- 2.39.5