saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Correct the top_file_merging_strategy documentation (#35774)

Browse source 
Top file merging does not work as described in the docs, this is being
corrected for the Carbon release. This commit fixes the docs so that
they A) are accurate for these older release branches, and B) refer to
the Carbon release as a point when top file merging was corrected.

These references to the Carbon release will need to be updated again
once we settle on a version number for Carbon.
This commit is contained in:
Erik Johnson 2016-08-26 11:25:56 -05:00 • committed by Nicole Thomas
parent 2a12795bac
commit 2fc61763d8
2 changed files with 49 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
doc/ref/configuration/minion.rst
View file

@ -1035,6 +1035,20 @@ environments is to isolate via the top file.
environment: dev
.. conf_minion:: state_top_saltenv
``state_top_saltenv``
---------------------
Default: not set
Set this option to an environment name, to ensure that *only* the top file from
that environment is considered during a :ref:`highstate <running-highstate>`.
.. code-block:: yaml
state_top_saltenv: base
.. conf_minion:: top_file_merging_strategy
``top_file_merging_strategy``
@ -1047,11 +1061,11 @@ for a :ref:`highstate <running-highstate>`, all environments' top files are
inspected. This config option determines how the SLS targets in those top files
are handled.
When set to ``merge``, the targets for all SLS files in all environments are
merged together. A given environment's SLS targets for the highstate will
consist of the collective SLS targets specified for that environment in all top
files. The environments will be merged in no specific order, for greater
control over the order in which the environments are merged use
When set to the default value of ``merge``, all SLS files are interpreted. The
first target expression for a given environment is kept, and when the same
target expression is used in a different top file evaluated later, it is
ignored. The environments will be evaluated in no specific order, for greater
control over the order in which the environments are evaluated use
:conf_minion:`env_order`.
When set to ``same``, then for each environment, only that environment's top
@ -1075,7 +1089,7 @@ Default: ``[]``
When :conf_minion:`top_file_merging_strategy` is set to ``merge``, and no
environment is specified for a :ref:`highstate <running-highstate>`, this
config option allows for the order in which top files are merged to be
config option allows for the order in which top files are evaluated to be
explicitly defined.
.. code-block:: yaml

33
doc/ref/states/top.rst
View file

@ -330,6 +330,14 @@ this, it can be helpful to set :conf_minion:`top_file_merging_strategy` to
top_file_merging_strategy: same
Another option would be to set :conf_minion:`state_top_saltenv` to a specific
environment, to ensure that any top files in other environments are
disregarded:
.. code-block:: yaml
state_top_saltenv: base
With :ref:`GitFS <tutorial-gitfs>`, it can also be helpful to simply manage
each environment's top file separately, and/or manually specify the environment
when executing the highstate to avoid any complicated merging scenarios.
@ -348,6 +356,7 @@ configuring a :ref:`highstate <running-highstate>`.
The following minion configuration options affect how top files are compiled
when no environment is specified:
- :conf_minion:`state_top_saltenv`
- :conf_minion:`top_file_merging_strategy`
- :conf_minion:`env_order`
- :conf_minion:`default_top`
@ -420,14 +429,30 @@ If the ``qa`` environment were specified, the :ref:`highstate
Scenario 2 - No Environment Specified, :conf_minion:`top_file_merging_strategy` is "merge"
------------------------------------------------------------------------------------------
In this scenario, ``base1`` from the ``base`` environment, ``dev1`` from the
``dev`` environment, and ``qa1`` from the ``qa`` environment are applied to all
minions. Additionally, ``base2`` from the ``base`` environment is applied to
minion1, and ``dev2`` from the ``dev`` environment is applied to minion2.
.. versionchanged:: Carbon
The default merging strategy has been renamed to from ``merge`` to
``default`` to reflect the fact that SLS names from identical targets in
matching environments from multiple top files are not actually merged.
In this scenario, assuming that the ``base`` environment's top file was
evaluated first, the ``base1``, ``dev1``, and ``qa1`` states would be applied
to all minions. If, for instance, the ``qa`` environment is not defined in
**/srv/salt/base/top.sls**, then the ``qa`` section in
**/srv/salt/dev/top.sls** would be used and the ``qa2`` states would be applied
to all minions.
Scenario 3 - No Environment Specified, :conf_minion:`top_file_merging_strategy` is "same"
-----------------------------------------------------------------------------------------
.. versionchanged:: Carbon
In prior versions, "same" did not quite work as described below (see
here__). This has now been corrected. It was decided that changing
something like top file handling in a point release had the potential to
unexpectedly impact users' top files too much, and it would be better to
make this correction in a feature release.
.. __: https://github.com/saltstack/salt/issues/35045
In this scenario, ``base1`` from the ``base`` environment is applied to all
minions. Additionally, ``dev2`` from the ``dev`` environment is applied to
minion2.