doc: add doc for custom config modules (#5548)

SC-1836
Fixes GH-4649

doc/rtd/development/module_creation.rst

@@ -163,6 +163,17 @@ in the correct location based on dependencies. If your module has no particular
 dependencies or is not necessary for a later boot stage, it should be placed
 in the ``cloud_final_modules`` section before the ``final-message`` module.
 
+Benefits of including your config module in upstream cloud-init
+===============================================================
+
+Config modules included in upstream cloud-init benefit from ongoing
+maintenance,
+compatibility with the rest of the codebase, and security fixes by the upstream
+development team.
+
+If this is not possible, one can add
+:ref:`custom out-of-tree config module<custom_configuration_module>`
+to cloud-init.
 
 .. _MetaSchema: https://github.com/canonical/cloud-init/blob/3bcffacb216d683241cf955e4f7f3e89431c1491/cloudinit/config/schema.py#L58
 .. _OSFAMILIES: https://github.com/canonical/cloud-init/blob/3bcffacb216d683241cf955e4f7f3e89431c1491/cloudinit/distros/__init__.py#L35

doc/rtd/reference/base_config_reference.rst

@@ -28,6 +28,8 @@ distribution supported by ``cloud-init``.
 Base configuration keys
 =======================
 
+.. _base_config_module_keys:
+
 Module keys
 -----------
 

doc/rtd/reference/custom_modules/custom_configuration_module.rst

@@ -2,3 +2,17 @@
 
 Custom Configuration Module
 ***************************
+
+Custom 3rd-party out-of-tree configuration modules can be added to cloud-init
+by:
+
+#. :ref:`Implement a config module<module_creation>` in a Python file with its
+   name starting with ``cc_``.
+
+#. Place the file where the rest of config modules are
+   On Ubuntu this path is typically:
+   `/usr/lib/python3/dist-packages/cloudinit/config/`.
+
+#. Extend the :ref:`base-configuration's <base_config_module_keys>`
+   ``cloud_init_modules``, ``cloud_config_modules`` or ``cloud_final_modules``
+   to let the config module run on one of those stages.