From c3a3eb79561b011de78b455a88a79a9347e97a0f Mon Sep 17 00:00:00 2001 From: Alberto Contreras Date: Fri, 26 Jul 2024 10:19:57 +0200 Subject: [PATCH] comments --- doc/rtd/reference/custom_modules.rst | 5 ++--- .../custom_modules/custom_cleaners.rst | 17 +++++++---------- .../custom_configuration_module.rst | 7 ++++++- .../custom_modules/custom_datasource.rst | 2 +- .../reference/custom_modules/custom_mergers.rst | 16 +++++----------- 5 files changed, 21 insertions(+), 26 deletions(-) diff --git a/doc/rtd/reference/custom_modules.rst b/doc/rtd/reference/custom_modules.rst index 687190d6cce..7885a003a99 100644 --- a/doc/rtd/reference/custom_modules.rst +++ b/doc/rtd/reference/custom_modules.rst @@ -1,9 +1,8 @@ Custom Modules ************** -Our reference section contains support information for ``cloud-init``. -This includes details on the network requirements, API definitions, support -matrices and so on. +This includes reference documentation on how to extend cloud-init with +custom / out-of-tree functionality. ----- diff --git a/doc/rtd/reference/custom_modules/custom_cleaners.rst b/doc/rtd/reference/custom_modules/custom_cleaners.rst index d7aec783693..17d57d4453a 100644 --- a/doc/rtd/reference/custom_modules/custom_cleaners.rst +++ b/doc/rtd/reference/custom_modules/custom_cleaners.rst @@ -9,20 +9,17 @@ the filesystem when the :ref:`cloud-init clean` command is invoked. The :command:`clean` operation is typically performed by image creators when preparing a golden image for clone and redeployment. The clean command -removes any cloud-init semaphores, allowing cloud-init to treat the next -boot of this image as the "first boot". When the image is next booted -cloud-init will performing all initial configuration based on any valid -datasource meta-data and user-data. - +removes any cloud-init internal state, allowing cloud-init to treat the next +boot of this image as the "first boot". Any executable scripts in this subdirectory will be invoked in lexicographical -order with run-parts when running the :command:`clean` command. - -Typical format of such scripts would be a ##- like the following: -:file:`/etc/cloud/clean.d/99-live-installer` +order when running the :command:`clean` command. -An example of a script is: +Example +======= .. code-block:: bash + $ cat /etc/cloud/clean.d/99-live-installer + #!/bin/sh sudo rm -rf /var/lib/installer_imgs/ sudo rm -rf /var/log/installer/ diff --git a/doc/rtd/reference/custom_modules/custom_configuration_module.rst b/doc/rtd/reference/custom_modules/custom_configuration_module.rst index 7dc590072e6..a26adf26eb4 100644 --- a/doc/rtd/reference/custom_modules/custom_configuration_module.rst +++ b/doc/rtd/reference/custom_modules/custom_configuration_module.rst @@ -9,10 +9,15 @@ by: #. :ref:`Implement a config module` in a Python file with its name starting with ``cc_``. -#. Place the file where the rest of config modules are +#. Place the file where the rest of config modules are located. On Ubuntu this path is typically: `/usr/lib/python3/dist-packages/cloudinit/config/`. #. Extend the :ref:`base-configuration's ` ``cloud_init_modules``, ``cloud_config_modules`` or ``cloud_final_modules`` to let the config module run on one of those stages. + +.. warning :: + The config jsonschema validation functionality is going to complain about + unknown config keys introduced by custom modules and there is not an easy + way for custom modules to define their keys schema-wise. diff --git a/doc/rtd/reference/custom_modules/custom_datasource.rst b/doc/rtd/reference/custom_modules/custom_datasource.rst index d3ddffbc593..2d5aa6c8463 100644 --- a/doc/rtd/reference/custom_modules/custom_datasource.rst +++ b/doc/rtd/reference/custom_modules/custom_datasource.rst @@ -10,7 +10,7 @@ Custom 3rd-party out-of-tree DataSources can be added to cloud-init by: #. Place that file in as a single Python module or package in folder included in ``$PYTHONPATH``. -#. Extend the :ref:`base-configuration`'s +#. Extend the base configuration's :ref:`datasource_pkg_list` to include the Python package where the DataSource is located. diff --git a/doc/rtd/reference/custom_modules/custom_mergers.rst b/doc/rtd/reference/custom_modules/custom_mergers.rst index c277983b140..b1af2c1d9f6 100644 --- a/doc/rtd/reference/custom_modules/custom_mergers.rst +++ b/doc/rtd/reference/custom_modules/custom_mergers.rst @@ -3,12 +3,9 @@ Custom Mergers ************** -TODO adapt and backreference - -Because the default -:ref:`merging` -algorithms and stragies may not always be desired, -the concept of customised merging was introduced through `merge classes`. +It is possible for users to inject their own :ref:`merging` +files to handle specific types of merging as they choose (the +basic ones included will handle lists, dicts, and strings). A `merge class` is a class definition providing functions that can be used to merge a given type with another given type. @@ -47,7 +44,7 @@ An example of one of these `merging classes` is the following: merged[k] = v return merged -As you can see, there is an ``_on_dict`` method here that will be given a +There is an ``_on_dict`` method here that will be given a source value, and a value to merge with. The result will be the merged object. This code itself is called by another merging class which "directs" the @@ -56,10 +53,7 @@ find a known object that will merge that type. An example of this can be found in the :file:`mergers/__init__.py` file (see ``LookupMerger`` and ``UnknownMerger``). -So, following the typical ``cloud-init`` approach of allowing source code to -be downloaded and used dynamically, it is possible for users to inject their -own merging files to handle specific types of merging as they choose (the -basic ones included will handle lists, dicts, and strings). Note how each +Note how each merge can have options associated with it, which affect how the merging is performed. For example, a dictionary merger can be told to overwrite instead of attempting to merge, or a string merger can be told to append strings