canonical
[docs]: Document drop-in 3rd party modules
Documentation request
Cloud-init provides code for drop-in 3rd party modules. These can be custom mergers, custom handlers, custom datasources, custom configuration modules, or custom cleaners.
These are categorically different than typical user configuration. Users are expected to run commands and write configurations. This customization to cloud-init expect the user to write code, which lands them in a grey zone between user and developer - call them "super user" for now.
Currently only custom mergers and custom handlers are documented, and the documentation for those is intermingled with "normal user" documentation. This "super user" documentation is likely confusing alongside normal configuration documentation, and should perhaps be relocated somewhere different for clarity (and linked from "normal user" documentation).
I imagine a document structure like this:
doc/rtd/reference/custom_modules/index.rst
doc/rtd/reference/custom_modules/custom_datasource.rst
doc/rtd/reference/custom_modules/custom_configuration_module.rst
doc/rtd/reference/custom_modules/custom_mergers.rst
doc/rtd/reference/custom_modules/custom_formats.rst
doc/rtd/reference/custom_modules/custom_cleaners.rst
The index.rst page should discuss the merits, drawbacks, and strategies for using these interfaces. Each sub-page should describe the interface and provide a brief example.
big +1 on separating those docs for "power users" with custom downstream image needs and behaviors. These scopres are atypical for most cloud-init users.
Distros can also be dropped-in, but there is no documentation on how to create a new distro. Issue created representing that effort: https://github.com/canonical/cloud-init/issues/5559.
