Merge branch 'documentation/update-best-practice' into 'master'

Add 'Perils of CDIST_ORDER_DEPENDENCY' sub-section

See merge request ungleich-public/cdist!777
This commit is contained in:
poljakowski 2019-05-06 17:12:47 +02:00
commit fb52bfb353
3 changed files with 140 additions and 0 deletions

View file

@ -224,3 +224,140 @@ in the repository for such content: It allows you to
easily distinguish what is used by cdist and what is not
and also to store all important files in one
repository.
Perils of CDIST_ORDER_DEPENDENCY
--------------------------------
With CDIST_ORDER_DEPENDENCY all types are executed in the order in which they
are created in the manifest. The current created object automatically depends
on the previously created object.
It essentially helps you to build up blocks of code that build upon each other
(like first creating the directory xyz than the file below the directory).
This can be helpful, but it can also be the source of *evil*.
CDIST_ORDER_DEPENDENCY easily causes unobvious dependency cycles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Let's see an example. Suppose you have special init manifest where among other
things you are assuring that remote host has packages `sudo` and `curl`
installed.
**init1**
.. code-block:: sh
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
for p in sudo curl
do
__package "${p}"
done
Then you have some other special init manifest where among other things you are
assuring `sudo` package is installed.
**init2**
.. code-block:: sh
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
__package sudo
Then you have third init manifest where you combine those two init manifests,
by including them:
**init**
.. code-block:: sh
sh -e "$__manifest/init1"
sh -e "$__manifest/init2"
The resulting init manifest is then equal to:
.. code-block:: sh
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
for p in sudo curl
do
__package "${p}"
done
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
__package sudo
In the end you get the following dependencies:
* `__package/curl` depends on `__package/sudo`
* `__package/sudo` depends on `__package/curl`
And here you have a circular dependency!
In the real world manifest can be quite complex, dependencies can become
complicated and circual dependencies are not so obvious. Resolving it can
become cumbersome.
**Practical solution?**
Instead of managing complex init manifests you can write custom types.
Each custom type can do one thing, it has well defined dependencies that will
not leak into init manifest. In custom type you can also add special explorers
and gencode.
Then, in init manifest you combine your complex types. It is:
* cleaner
* easier to follow
* easier to maintain
* easier to debug.
CDIST_ORDER_DEPENDENCY kills parallelization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Suppose you have defined CDIST_ORDER_DEPENDENCY and then, among other things,
you specify creation of three, by nature independent, files.
**init**
.. code-block:: sh
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
...
__file /tmp/file1
__file /tmp/file2
__file /tmp/file3
...
Due to defined CDIST_ORDER_DEPENDENCY cdist will execute them in specified order.
It is better to use CDIST_ORDER_DEPENDENCY in well defined blocks:
**init**
.. code-block:: sh
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
...
unset CDIST_ORDER_DEPENDENCY
__file /tmp/file1
__file /tmp/file2
__file /tmp/file3
CDIST_ORDER_DEPENDENCY=1
export CDIST_ORDER_DEPENDENCY
...
unset CDIST_ORDER_DEPENDENCY

View file

@ -163,6 +163,8 @@ automatically depends on the previously created object.
It essentially helps you to build up blocks of code that build upon each other
(like first creating the directory xyz than the file below the directory).
Read also about `perils of CDIST_ORDER_DEPENDENCY <cdist-best-practice.html#perils-of-cdist-order-dependency>`_.
Overrides
---------

View file

@ -323,6 +323,7 @@ CDIST_OVERRIDE
CDIST_ORDER_DEPENDENCY
Create dependencies based on the execution order (see \`cdist manifest <cdist-manifest.html>\`_).
Read also about \`perils of CDIST_ORDER_DEPENDENCY <cdist-best-practice.html#perils-of-cdist-order-dependency>\`_.
CDIST_REMOTE_EXEC
Use this command for remote execution (should behave like ssh).