Skip to content

Add docs for mod_aggregate state-level keywords #18672

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 4, 2014
Merged

Add docs for mod_aggregate state-level keywords #18672

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aa964e5
Added state_aggregate placeholders to the master/minion conf files
whiteinge Dec 2, 2014
54d8760
Added docs for the state-level aggregate keyword
whiteinge Dec 2, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions conf/master
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,6 +327,14 @@
# If set to 'changes', the output will be full unless the state didn't change.
#state_output: full

# Automatically aggregate all states that have support for mod_aggregate by
# setting to True. Or pass a list of state module names to automatically
# aggregate just those types.
#
# state_aggregate:
# - pkg
#
#state_aggregate: False

##### File Server settings #####
##########################################
Expand Down
8 changes: 8 additions & 0 deletions conf/minion
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,14 @@
# Top file to execute if startup_states is 'top':
#top_file: ''

# Automatically aggregate all states that have support for mod_aggregate by
# setting to True. Or pass a list of state module names to automatically
# aggregate just those types.
#
# state_aggregate:
# - pkg
#
#state_aggregate: False

##### File Directory Settings #####
##########################################
Expand Down
53 changes: 40 additions & 13 deletions doc/ref/states/aggregate.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,44 +13,71 @@ all, it makes Salt much more dynamic.
How it Works
============

The best example is the `pkg` state. One of the major requests in Salt has long
The best example is the ``pkg`` state. One of the major requests in Salt has long
been adding the ability to install all packages defined at the same time. The
mod_aggregate system makes this a reality. While executing Salt's state system,
when a `pkg` state is reached the ``mod_aggregate`` function in the state module
is called. For `pkg` this function scans all of the other states that are slated
when a ``pkg`` state is reached the ``mod_aggregate`` function in the state module
is called. For ``pkg`` this function scans all of the other states that are slated
to run, and picks up the references to ``name`` and ``pkgs``, then adds them to
``pkgs`` in the first state. The result is calling yum/apt-get/pacman etc. just
once to install of the packages as part of the first package install.
``pkgs`` in the first state. The result is a single call to yum, apt-get,
pacman, etc as part of the first package install.

How to Use it
=============


.. note::

Since this option changes the basic behavior of the state runtime, after
it is enabled states should be executed using `test=True` to ensure that
the desired behavior is preserved.

Since this behavior can dramatically change the flow of configuration
management inside of Salt it is disabled by default. But enabling it is easy.
In config files
---------------

The first way to enable aggregation is with a configuration option in either
the master or minion configuration files. Salt will invoke ``mod_aggregate``
the first time it encounters a state module that has aggregate support.

If this option is set in the master config it will apply to all state runs on
all minions, if set in the minion config it will only apply to said minion.

To enable for all states just add:
Enable for all states:

.. code-block:: yaml

state_aggregate: True

Similarly only specific states can be enabled:
Enable for only specific state modules:

.. code-block:: yaml

state_aggregate:
- pkg

To the master or minion config and restart the master or minion, if this option
is set in the master config it will apply to all state runs on all minions, if
set in the minion config it will only apply to said minion.
In states
---------

The second way to enable aggregation is with the state-level ``aggregate``
keyword. In this configuration, Salt will invoke the ``mod_aggregate`` function
the first time it encounters this keyword. Any additional occurances of the
keyword will be ignored as the aggregation has already taken place.

The following example will trigger ``mod_aggregate`` when the ``lamp_stack``
state is processed resulting in a single call to the underlying package
manager.

.. code-block:: yaml

lamp_stack:
pkg.installed:
- pkgs:
- php
- mysql-client
- aggregate: True

memcached:
pkg.installed:
- name: memcached

Adding mod_aggregate to a State Module
======================================
Expand Down