valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-07 00:55:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge branch '2015.5' into '2015.8'

Browse Source 
Conflicts:
  - doc/ref/states/include.rst
  - doc/topics/cloud/reactor.rst
  - doc/topics/reactor/index.rst
  - doc/topics/releases/2015.5.10.rst
  - doc/topics/tutorials/states_pt5.rst
  - doc/topics/windows/windows-package-manager.rst
  - salt/config.py
  - salt/modules/state.py
  - salt/states/grains.py
  - tests/integration/modules/sysmod.py
  - tests/unit/states/grains_test.py
This commit is contained in:
rallytime 2016-03-24 15:48:00 -06:00
commit 7554d0f42d
43 changed files with 572 additions and 364 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/faq.rst
View File

@ -38,8 +38,8 @@ I'm seeing weird behavior (including but not limited to packages not installing
This is often caused by SELinux. Try disabling SELinux or putting it in
permissive mode and see if the weird behavior goes away.
My script runs every time I run a *state.highstate*. Why?
---------------------------------------------------------
My script runs every time I run a *state.apply*. Why?
-----------------------------------------------------
You are probably using :mod:`cmd.run <salt.states.cmd.run>` rather than
:mod:`cmd.wait <salt.states.cmd.wait>`. A :mod:`cmd.wait
@ -134,11 +134,11 @@ should be opened on our tracker_, with the following information:
Why aren't my custom modules/states/etc. available on my Minions?
-----------------------------------------------------------------
Custom modules are only synced to Minions when :mod:`state.highstate
<salt.modules.state.highstate>`, :mod:`saltutil.sync_modules
Custom modules are only synced to Minions when :mod:`state.apply
<salt.modules.state.apply_>`, :mod:`saltutil.sync_modules
<salt.modules.saltutil.sync_modules>`, or :mod:`saltutil.sync_all
<salt.modules.saltutil.sync_all>` is run. Similarly, custom states are only
synced to Minions when :mod:`state.highstate <salt.modules.state.highstate>`,
synced to Minions when :mod:`state.apply <salt.modules.state.apply_>`,
:mod:`saltutil.sync_states <salt.modules.saltutil.sync_states>`, or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` is run.

6
doc/ref/configuration/minion.rst
View File

@ -331,10 +331,10 @@ Verify and set permissions on configuration directories at startup.
.. note::
When marked as True the verify_env option requires WRITE access to the
When set to ``True`` the verify_env option requires WRITE access to the
configuration directory (/etc/salt/). In certain situations such as
mounting /etc/salt/ as read-only for templating this will create a
stack trace when state.highstate is called.
mounting /etc/salt/ as read-only for templating this will create a stack
trace when :py:func:`state.apply <salt.modules.state.apply_>` is called.
.. conf_minion:: cache_jobs

2
doc/ref/modules/index.rst
View File

@ -32,7 +32,7 @@ default this is `/srv/salt/_modules` on Linux systems.
Modules placed in ``_modules/`` will be synced to the minions when any of the following
Salt functions are called:
* :mod:`state.highstate <salt.modules.state.highstate>`
* :mod:`state.apply <salt.modules.state.apply_>`
* :mod:`saltutil.sync_modules <salt.modules.saltutil.sync_modules>`
* :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`

7
doc/ref/renderers/index.rst
View File

@ -121,11 +121,10 @@ Custom renderers must be placed in a ``_renderers`` directory within the
:conf_master:`file_roots` specified by the master config file.
Custom renderers are distributed when any of the following are run:
:mod:`state.highstate <salt.modules.state.highstate>`
:mod:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>`
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
- :py:func:`state.apply <salt.modules.state.apply_>`
- :py:func:`saltutil.sync_renderers <salt.modules.saltutil.sync_renderers>`
- :py:func:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
Any custom renderers which have been synced to a minion, that are named the
same as one of Salt's default set of renderers, will take the place of the

7
doc/ref/returners/index.rst
View File

@ -289,11 +289,10 @@ Place custom returners in a ``_returners`` directory within the
:conf_master:`file_roots` specified by the master config file.
Custom returners are distributed when any of the following are called:
:mod:`state.highstate <salt.modules.state.highstate>`
:mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>`
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
- :mod:`state.apply <salt.modules.state.apply_>`
- :mod:`saltutil.sync_returners <salt.modules.saltutil.sync_returners>`
- :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>`
Any custom returners which have been synced to a minion that are named the
same as one of Salt's default set of returners will take the place of the

2
doc/ref/states/compiler_ordering.rst
View File

@ -226,7 +226,7 @@ In the following case:
include:
- qux
In the above case if `state.sls foo` were called then the formulas will be
In the above case if ``state.apply foo`` were called then the formulas will be
loaded in the following order:
1. quo

12
doc/ref/states/highstate.rst
View File

@ -34,7 +34,7 @@ Include declaration
Defines a list of :ref:`module-reference` strings to include in this ``SLS``.
Occurs only in the top level of the highstate structure.
Occurs only in the top level of the SLS data structure.
Example:
@ -58,10 +58,10 @@ file ``salt://edit/vim.sls``.
ID declaration
--------------
Defines an individual highstate component. Always references a value of a
dictionary containing keys referencing :ref:`state-declaration` and
:ref:`requisite-declaration`. Can be overridden by a :ref:`name-declaration` or
a :ref:`names-declaration`.
Defines an individual :ref:`highstate <running-highstate>` component. Always
references a value of a dictionary containing keys referencing
:ref:`state-declaration` and :ref:`requisite-declaration`. Can be overridden by
a :ref:`name-declaration` or a :ref:`names-declaration`.
Occurs on the top level or under the :ref:`extend-declaration`.
@ -72,7 +72,7 @@ ID declarations with the same name will be ignored.
.. note:: Naming gotchas
In Salt versions earlier than 0.9.7, ID declarations containing dots would
result in unpredictable highstate output.
result in unpredictable output.
.. _extend-declaration:

7
doc/ref/states/include.rst
View File

@ -74,10 +74,10 @@ another SLS file or a specific id. The component is excluded after the
high data has been compiled, so nothing should be able to override an
exclude.
Since the exclude can remove an id or an SLS the type of component to exclude
Since the exclude can remove an id or an sls the type of component to exclude
needs to be defined. An exclude statement that verifies that the running
highstate does not contain the ``http`` SLS and the ``/etc/vimrc`` id would
look like this:
:ref:`highstate <running-highstate>` does not contain the ``http`` sls and the
``/etc/vimrc`` id would look like this:
.. code-block:: yaml
@ -89,3 +89,4 @@ look like this:
The current state processing flow checks for duplicate IDs before
processing excludes. An error occurs if duplicate IDs are present even if
one of the IDs is targeted by an ``exclude``.

4
doc/ref/states/index.rst
View File

@ -213,7 +213,7 @@ earlier, requires `pip`_ to be installed system-wide. Let's execute this state:
.. code-block:: bash
salt-call state.sls pep8
salt-call state.apply pep8
The execution output would be something like:
@ -292,7 +292,7 @@ Let's run it, once:
.. code-block:: bash
salt-call state.sls pep8
salt-call state.apply pep8
The output is:

14
doc/ref/states/layers.rst
View File

@ -46,7 +46,7 @@ Low State
=========
The `Low State` layer is the list of low chunks "evaluated" in order. To see
what the low state looks like for a highstate, run:
what the low state looks like for a :ref:`highstate <running-highstate>`, run:
.. code-block:: bash
@ -96,11 +96,12 @@ The SLS layer can be called directly to execute individual sls formulas.
in a much more dynamic way by combining pillar and other sources, and the
SLS can be dynamically generated.
To call a single SLS formula named ``edit.vim``, execute ``state.sls``:
To call a single SLS formula named ``edit.vim``, execute :py:func:`state.apply
<salt.modules.state.apply_>` and pass ``edit.vim`` as an argument:
.. code-block:: bash
salt '*' state.sls edit.vim
salt '*' state.apply edit.vim
.. _state-layers-highstate:
@ -116,11 +117,12 @@ assigned from the master without needing to execute or configure anything on
the target minion. This also means that the minion can independently retrieve
information about its complete configuration from the master.
To execute the High State call ``state.highstate``:
To execute the :ref:`highstate <running-highstate>` use :py:func:`state.apply
<salt.modules.state.apply_>`:
.. code-block:: bash
salt '*' state.highstate
salt '*' state.apply
.. _state-layers-orchestrate:
@ -131,4 +133,4 @@ The orchestrate layer expresses the highest functional layer of Salt's automated
logic systems. The Overstate allows for stateful and functional orchestration
of routines from the master. The orchestrate defines in data execution stages
which minions should execute states, or functions, and in what order using
requisite logic.
requisite logic.

8
doc/ref/states/startup.rst
View File

@ -13,8 +13,8 @@ executed at startup. The options are `startup_states`, `sls_list`, and
The `startup_states` option can be passed one of a number of arguments to
define how to execute states. The available options are:
highstate
Execute ``state.highstate``
:ref:`highstate <running-highstate>`
Execute :py:func:`state.apply <salt.modules.state.apply_>`
sls
Read in the ``sls_list`` option and execute the named sls files
@ -26,8 +26,8 @@ top
Examples:
---------
Execute ``state.highstate`` when starting the minion:
Execute :py:func:`state.apply <salt.modules.state.apply_>` to run the
:ref:`highstate <running-highstate>` when starting the minion:
.. code-block:: yaml

10
doc/ref/states/testing.rst
View File

@ -11,8 +11,8 @@ interface can be invoked on any of the major state run functions:
.. code-block:: bash
salt '*' state.highstate test=True
salt '*' state.sls test=True
salt '*' state.apply test=True
salt '*' state.apply mysls test=True
salt '*' state.single test=True
The test run is mandated by adding the ``test=True`` option to the states. The
@ -28,6 +28,6 @@ states can still be run by calling test=False:
.. code-block:: bash
salt '*' state.highstate test=False
salt '*' state.sls test=False
salt '*' state.single test=False
salt '*' state.apply test=False
salt '*' state.apply mysls test=False
salt '*' state.single test=False

4
doc/ref/states/writing.rst
View File

@ -56,8 +56,8 @@ Using Custom State Modules
Place your custom state modules inside a ``_states`` directory within the
:conf_master:`file_roots` specified by the master config file. These custom
state modules can then be distributed in a number of ways. Custom state modules
are distributed when :mod:`state.highstate <salt.modules.state.highstate>` is
run, or by executing the :mod:`saltutil.sync_states
are distributed when :py:func:`state.apply <salt.modules.state.apply_>` is run,
or by executing the :mod:`saltutil.sync_states
<salt.modules.saltutil.sync_states>` or :mod:`saltutil.sync_all
<salt.modules.saltutil.sync_all>` functions.

9
doc/topics/cloud/deploy.rst
View File

@ -65,13 +65,14 @@ Post-Deploy Commands
====================
Once a minion has been deployed, it has the option to run a salt command.
Normally, this would be the state.highstate command, which would finish
provisioning the VM. Another common option is state.sls, or for just testing,
test.ping. This is configured in the main cloud config file:
Normally, this would be the :py:func:`state.apply <salt.modules.state.apply_>`,
which would finish provisioning the VM. Another common option (for testing) is
to use :py:func:`test.ping <salt.modules.test.ping>`. This is configured in the
main cloud config file:
.. code-block:: yaml
start_action: state.highstate
start_action: state.apply
This is currently considered to be experimental functionality, and may not work

30
doc/topics/cloud/reactor.rst
View File

@ -202,8 +202,8 @@ When Salt Cloud creates an instance, by default it will install the Salt Minion
onto the instance, along with any specified minion configuration, and
automatically accept that minion's keys on the master. One of the configuration
options that can be specified is ``startup_states``, which is commonly set to
``highstate``. This will tell the minion to immediately apply a highstate, as
soon as it is able to do so.
``highstate``. This will tell the minion to immediately apply a :ref:`highstate
<running-highstate>`, as soon as it is able to do so.
This can present a problem with some system images on some cloud hosts. For
instance, Salt Cloud can be configured to log in as either the ``root`` user, or
@ -213,12 +213,13 @@ log in (notably EC2, with their ``ec2-user`` login), most cloud hosts fall
back to ``root`` as the default login on all images, including for operating
systems (such as Ubuntu) which normally disallow remote ``root`` login.
For users of these operating systems, it is understandable that a highstate
would include configuration to block remote ``root`` logins again. However,
Salt Cloud may not have finished cleaning up its deployment files by the time
the minion process has started, and kicked off a highstate run. Users have
reported errors from Salt Cloud getting locked out while trying to clean up
after itself.
For users of these operating systems, it is understandable that a
:ref:`highstate <running-highstate>` would include configuration to block
remote ``root`` logins again. However, Salt Cloud may not have finished
cleaning up its deployment files by the time the minion process has started,
and kicked off a :ref:`highstate <running-highstate>` run. Users have reported
errors from Salt Cloud getting locked out while trying to clean up after
itself.
The goal of a startup state may be achieved using the Event Reactor. Because a
minion fires an event when it is able to receive commands, this event can
@ -231,17 +232,18 @@ the reactor system to the right ``sls`` file:
- 'salt/cloud/*/created':
- '/srv/reactor/startup_highstate.sls'
And the following ``sls`` file will start a highstate run on the target minion:
And the following ``sls`` file will start a :ref:`highstate
<running-highstate>` run on the target minion:
.. code-block:: yaml
# /srv/reactor/startup_highstate.sls
reactor_highstate:
cmd.state.highstate:
cmd.state.apply:
- tgt: {{ data['name'] }}
Because this event will not be fired until Salt Cloud has cleaned up after
itself, the highstate run will not step on Salt Cloud's toes. And because every
file on the minion is configurable, including ``/etc/salt/minion``, the
``startup_states`` can still be configured for future minion restarts, if
desired.
itself, the :ref:`highstate <running-highstate>` run will not step on
salt-cloud's toes. And because every file on the minion is configurable,
including ``/etc/salt/minion``, the ``startup_states`` can still be configured
for future minion restarts, if desired.

9
doc/topics/development/conventions/formulas.rst
View File

@ -367,7 +367,8 @@ variables or interact.
for :ref:`any of the alternate renderers <all-salt.renderers>` in Salt.)
* Highstate can be thought of as a human-friendly data structure; easy to write
and easy to read.
* Salt's state compiler validates the highstate and compiles it to low state.
* Salt's state compiler validates the :ref:`highstate <running-highstate>` and
compiles it to low state.
* Low state can be thought of as a machine-friendly data structure. It is a
list of dictionaries that each map directly to a function call.
* Salt's state system finally starts and executes on each "chunk" in the low
@ -1302,9 +1303,9 @@ structure can be performed by with the :py:func:`state.show_sls
salt '*' state.show_sls apache
Salt Formulas can then be tested by running each ``.sls`` file via
:py:func:`state.sls <salt.modules.state.sls>` and checking the output for the
success or failure of each state in the Formula. This should be done for each
supported platform.
:py:func:`state.apply <salt.modules.state.apply_>` and checking the output for
the success or failure of each state in the Formula. This should be done for
each supported platform.
.. ............................................................................

7
doc/topics/development/dunder_dictionaries.rst
View File

@ -91,8 +91,9 @@ During a state run the ``__context__`` dictionary persists across all states
that are run and then is destroyed when the state ends.
When running an execution module ``__context__`` persists across all module
executions until the modules are refreshed; such as when ``saltutils.sync_all``
or ``state.highstate`` are executed.
executions until the modules are refreshed; such as when
:py:func:`saltutil.sync_all <salt.modules.saltutil.sync_all>` or
:py:func:`state.apply <salt.modules.state.apply_>` are executed.
A great place to see how to use ``__context__`` is in the cp.py module in
salt/modules/cp.py. The fileclient authenticates with the master when it is
@ -109,4 +110,4 @@ each file. Here is an example from salt/modules/cp.py:
.. note:: Because __context__ may or may not have been destroyed, always be
sure to check for the existence of the key in __context__ and
generate the key before using it.
generate the key before using it.

62
doc/topics/jobs/schedule.rst
View File

@ -26,25 +26,28 @@ and could step on each other or otherwise double execute. The default for
States are executed on the minion, as all states are. You can pass positional
arguments and provide a yaml dict of named arguments.
The below example will schedule the command ``state.apply httpd test=True``
every 3600 seconds (every hour):
.. code-block:: yaml
schedule:
job1:
function: state.sls
function: state.apply
seconds: 3600
args:
- httpd
kwargs:
test: True
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour)
This next example will schedule the command ``state.apply httpd test=True``
every 3600 seconds (every hour) splaying the time between 0 and 15 seconds:
.. code-block:: yaml
schedule:
job1:
function: state.sls
function: state.apply
seconds: 3600
args:
- httpd
@ -52,14 +55,15 @@ This will schedule the command: state.sls httpd test=True every 3600 seconds
test: True
splay: 15
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) splaying the time between 0 and 15 seconds
Finally, the next example will schedule the command ``state.apply httpd
test=True`` every 3600 seconds (every hour) splaying the time between 10 and 15
seconds:
.. code-block:: yaml
schedule:
job1:
function: state.sls
function: state.apply
seconds: 3600
args:
- httpd
@ -69,34 +73,34 @@ This will schedule the command: state.sls httpd test=True every 3600 seconds
start: 10
end: 15
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) splaying the time between 10 and 15 seconds
.. versionadded:: 2014.7.0
Frequency of jobs can also be specified using date strings supported by
the python dateutil library. This requires python-dateutil to be installed on
the minion.
For example, this will schedule the command ``state.apply httpd test=True`` at
5:00pm localtime on the minion.
.. code-block:: yaml
schedule:
job1:
function: state.sls
function: state.apply
args:
- httpd
kwargs:
test: True
when: 5:00pm
This will schedule the command: state.sls httpd test=True at 5:00pm minion
localtime.
To schedule the command ``state.apply httpd test=True`` at 5pm on Monday,
Wednesday, and Friday, and 3pm on Tuesday and Thursday, use the following:
.. code-block:: yaml
schedule:
job1:
function: state.sls
function: state.apply
args:
- httpd
kwargs:
@ -108,14 +112,16 @@ localtime.
- Thursday 3:00pm
- Friday 5:00pm
This will schedule the command: state.sls httpd test=True at 5pm on Monday,
Wednesday, and Friday, and 3pm on Tuesday and Thursday.
Time ranges are also supported. For example, the below configuration will
schedule the command ``state.apply httpd test=True`` every 3600 seconds (every
hour) between the hours of 8am and 5pm. The range parameter must be a
dictionary with the date strings using the ``dateutil`` format.
.. code-block:: yaml
schedule:
job1:
function: state.sls
function: state.apply
seconds: 3600
args:
- httpd
@ -125,18 +131,18 @@ Wednesday, and Friday, and 3pm on Tuesday and Thursday.
start: 8:00am
end: 5:00pm
This will schedule the command: state.sls httpd test=True every 3600 seconds
(every hour) between the hours of 8am and 5pm. The range parameter must be a
dictionary with the date strings using the dateutil format. This requires
python-dateutil to be installed on the minion.
.. note::
Using time ranges requires python-dateutil_ to be installed on the minion.
.. _python-dateutil: https://github.com/dateutil/dateutil#dateutil---powerful-extensions-to-datetime
.. versionadded:: 2014.7.0
The scheduler also supports ensuring that there are no more than N copies of
a particular routine running. Use this for jobs that may be long-running
and could step on each other or pile up in case of infrastructure outage.
The scheduler also supports ensuring that there are no more than N copies of a
particular routine running. Use this for jobs that may be long-running and
could step on each other or pile up in case of infrastructure outage.
The default for maxrunning is 1.
The default for ``maxrunning`` is 1.
.. code-block:: yaml
@ -163,14 +169,14 @@ States
Highstates
==========
To set up a highstate to run on a minion every 60 minutes set this in the
minion config or pillar:
To set up a :ref:`highstate <running-highstate>` to run on a minion every 60
minutes set this in the minion config or pillar:
.. code-block:: yaml
schedule:
highstate:
function: state.highstate
function: state.apply
minutes: 60
Time intervals can be specified as seconds, minutes, hours, or days.

6
doc/topics/master_tops/index.rst
View File

@ -3,8 +3,8 @@ Master Tops System
==================
In 0.10.4 the `external_nodes` system was upgraded to allow for modular
subsystems to be used to generate the top file data for a highstate run on
the master.
subsystems to be used to generate the top file data for a :ref:`highstate
<running-highstate>` run on the master.
The old `external_nodes` option has been removed.
The master tops system contains a number of subsystems that
@ -74,4 +74,4 @@ a degenerate example:
minion
----------
base:
- test
- test

9
doc/topics/pillar/index.rst
View File

@ -352,14 +352,9 @@ Pillar data can be set at the command line like the following example:
.. code-block:: bash
salt '*' state.highstate pillar='{"cheese": "spam"}'
salt '*' state.apply pillar='{"cheese": "spam"}'
This will create a dict with a key of 'cheese' and a value of 'spam'. A list
can be created like this:
.. code-block:: bash
salt '*' state.highstate pillar='["cheese", "milk", "bread"]'
This will add a Pillar key of ``cheese`` with its value set to ``spam``.
.. note::

55
doc/topics/reactor/index.rst
View File

@ -75,7 +75,7 @@ Here is a simple reactor sls:
{% if data['id'] == 'mysql1' %}
highstate_run:
local.state.highstate:
local.state.apply:
- tgt: mysql1
{% endif %}
@ -85,8 +85,8 @@ the minion is ``mysql1``) then the following reaction is defined. The same
data structure and compiler used for the state system is used for the reactor
system. The only difference is that the data is matched up to the salt command
API and the runner system. In this example, a command is published to the
``mysql1`` minion with a function of ``state.highstate``. Similarly, a runner
can be called:
``mysql1`` minion with a function of :py:func:`state.apply
<salt.modules.state.apply_>`. Similarly, a runner can be called:
.. code-block:: yaml
@ -306,8 +306,8 @@ Passing event data to Minions or Orchestrate as Pillar
------------------------------------------------------
An interesting trick to pass data from the Reactor script to
``state.highstate`` or ``state.sls`` is to pass it as inline Pillar data since
both functions take a keyword argument named ``pillar``.
:py:func:`state.apply <salt.modules.state.apply_>` is to pass it as inline
Pillar data since both functions take a keyword argument named ``pillar``.
The following example uses Salt's Reactor to listen for the event that is fired
when the key for a new minion is accepted on the master using ``salt-key``.
@ -320,9 +320,9 @@ when the key for a new minion is accepted on the master using ``salt-key``.
- 'salt/key':
- /srv/salt/haproxy/react_new_minion.sls
The Reactor then fires a ``state.sls`` command targeted to the HAProxy servers
and passes the ID of the new minion from the event to the state file via inline
Pillar.
The Reactor then fires a ::py:func:`state.apply <salt.modules.state.apply_>`
command targeted to the HAProxy servers and passes the ID of the new minion
from the event to the state file via inline Pillar.
:file:`/srv/salt/haproxy/react_new_minion.sls`:
@ -330,7 +330,7 @@ Pillar.
{% if data['act'] == 'accept' and data['id'].startswith('web') %}
add_new_minion_to_pool:
local.state.sls:
local.state.apply:
- tgt: 'haproxy*'
- arg:
- haproxy.refresh_pool
@ -343,7 +343,7 @@ The above command is equivalent to the following command at the CLI:
.. code-block:: bash
salt 'haproxy*' state.sls haproxy.refresh_pool 'pillar={new_minion: minionid}'
salt 'haproxy*' state.apply haproxy.refresh_pool 'pillar={new_minion: minionid}'
This works with Orchestrate files as well:
@ -391,9 +391,9 @@ In this example, we're going to assume that we have a group of servers that
will come online at random and need to have keys automatically accepted. We'll
also add that we don't want all servers being automatically accepted. For this
example, we'll assume that all hosts that have an id that starts with 'ink'
will be automatically accepted and have state.highstate executed. On top of
this, we're going to add that a host coming up that was replaced (meaning a new
key) will also be accepted.
will be automatically accepted and have :py:func:`state.apply
<salt.modules.state.apply_>` executed. On top of this, we're going to add that
a host coming up that was replaced (meaning a new key) will also be accepted.
Our master configuration will be rather simple. All minions that attempte to
authenticate will match the :strong:`tag` of :strong:`salt/auth`. When it comes
@ -448,17 +448,17 @@ Ink servers in the master configuration.
.. code-block:: yaml
{# When an Ink server connects, run state.highstate. #}
{# When an Ink server connects, run state.apply. #}
highstate_run:
local.state.highstate:
local.state.apply:
- tgt: {{ data['id'] }}
- ret: smtp
The above will also return the highstate result data using the `smtp_return`
returner (use virtualname like when using from the command line with `--return`).
The returner needs to be configured on the minion for this to work.
See :mod:`salt.returners.smtp_return <salt.returners.smtp_return>` documentation
for that.
The above will also return the :ref:`highstate <running-highstate>` result data
using the `smtp_return` returner (use virtualname like when using from the
command line with `--return`). The returner needs to be configured on the
minion for this to work. See :mod:`salt.returners.smtp_return
<salt.returners.smtp_return>` documentation for that.
.. _minion-start-reactor:
@ -466,11 +466,12 @@ Syncing Custom Types on Minion Start
====================================
Salt will sync all custom types (by running a :mod:`saltutil.sync_all
<salt.modules.saltutil.sync_all>`) on every highstate. However, there is a
chicken-and-egg issue where, on the initial highstate, a minion will not yet
have these custom types synced when the top file is first compiled. This can be
worked around with a simple reactor which watches for ``minion_start`` events,
which each minion fires when it first starts up and connects to the master.
<salt.modules.saltutil.sync_all>`) on every :ref:`highstate
<running-highstate>`. However, there is a chicken-and-egg issue where, on the
initial :ref:`highstate <running-highstate>`, a minion will not yet have these
custom types synced when the top file is first compiled. This can be worked
around with a simple reactor which watches for ``minion_start`` events, which
each minion fires when it first starts up and connects to the master.
On the master, create **/srv/reactor/sync_grains.sls** with the following
contents:
@ -490,8 +491,8 @@ And in the master config file, add the following reactor configuration:
- /srv/reactor/sync_grains.sls
This will cause the master to instruct each minion to sync its custom grains
when it starts, making these grains available when the initial highstate is
executed.
when it starts, making these grains available when the initial :ref:`highstate
<running-highstate>` is executed.
Other types can be synced by replacing ``local.saltutil.sync_grains`` with
``local.saltutil.sync_modules``, ``local.saltutil.sync_all``, or whatever else

13
doc/topics/releases/2015.5.10.rst
View File

@ -19,3 +19,16 @@ in the Salt Master configuration.
(No additional fixes are contained in this release).
Read Before Upgrading Debian 8 (Jessie) from Salt Versions Earlier than 2015.5.9
================================================================================
Salt ``systemd`` service files are missing the following statement in these versions:
.. code-block:: ini
[Service]
KillMode=process
This statement must be added to successfully upgrade on these earlier versions
of Salt.

21
doc/topics/targeting/grains.rst
View File

@ -168,12 +168,11 @@ keys in the :ref:`dict <python2:typesmapping>` are the names of the grains and
the values are the values.
Custom grains should be placed in a ``_grains`` directory located under the
:conf_master:`file_roots` specified by the master config file. The default path
would be ``/srv/salt/_grains``. Custom grains will be
distributed to the minions when :mod:`state.highstate
<salt.modules.state.highstate>` is run, or by executing the
:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
:conf_master:`file_roots` specified by the master config file. The default
path would be ``/srv/salt/_grains``. Custom grains will be distributed to the
minions when :py:func:`state.apply <salt.modules.state.apply_>` is run, or by
executing the :mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>`
or :mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.
Grains are easy to write, and only need to return a dictionary. A common
approach would be code something similar to the following:
@ -197,9 +196,9 @@ change, consider using :doc:`Pillar <../pillar/index>` instead.
Custom grains will not be available in the top file until after the first
:ref:`highstate <running-highstate>`. To make custom grains available on a
minion's first highstate, it is recommended to use :ref:`this example
<minion-start-reactor>` to ensure that the custom grains are synced when
the minion starts.
minion's first :ref:`highstate <running-highstate>`, it is recommended to
use :ref:`this example <minion-start-reactor>` to ensure that the custom
grains are synced when the minion starts.
Loading Custom Grains
---------------------
@ -295,7 +294,7 @@ Syncing Grains
==============
Syncing grains can be done a number of ways, they are automatically synced when
:mod:`state.highstate <salt.modules.state.highstate>` is called, or (as noted
above) the grains can be manually synced and reloaded by calling the
:mod:`state.apply <salt.modules.state.apply_>` is called, or (as noted above)
the grains can be manually synced and reloaded by calling the
:mod:`saltutil.sync_grains <salt.modules.saltutil.sync_grains>` or
:mod:`saltutil.sync_all <salt.modules.saltutil.sync_all>` functions.

16
doc/topics/troubleshooting/index.rst
View File

@ -85,17 +85,17 @@ The ``salt-call`` command was originally developed for aiding in the development
of new Salt modules. Since then, many applications have been developed for
running any Salt module locally on a minion. These range from the original
intent of salt-call, development assistance, to gathering more verbose output
from calls like :mod:`state.highstate <salt.modules.state.highstate>`.
from calls like :mod:`state.apply <salt.modules.state.apply_>`.
When creating your state tree, it is generally recommended to invoke
:mod:`state.highstate <salt.modules.state.highstate>` with ``salt-call``. This
displays far more information about the highstate execution than calling it
remotely. For even more verbosity, increase the loglevel with the same argument
as ``salt-minion``:
When initially creating your state tree, it is generally recommended to invoke
:mod:`state.apply <salt.modules.state.apply_>` directly from the minion with
``salt-call``, rather than remotely from the master. This displays far more
information about the execution than calling it remotely. For even more
verbosity, increase the loglevel using the ``-l`` argument:
.. code-block:: bash
salt-call -l debug state.highstate
salt-call -l debug state.apply
The main difference between using ``salt`` and using ``salt-call`` is that
``salt-call`` is run from the minion, and it only runs the selected function on
@ -262,4 +262,4 @@ Debugging the Master and Minion
A list of common :doc:`master</topics/troubleshooting/master>` and
:doc:`minion</topics/troubleshooting/minion>` troubleshooting steps provide a
starting point for resolving issues you may encounter.
starting point for resolving issues you may encounter.

5
doc/topics/troubleshooting/master.rst
View File

@ -181,8 +181,9 @@ Commands Time Out or Do Not Return Output
=========================================
Depending on your OS (this is most common on Ubuntu due to apt-get) you may
sometimes encounter times where your highstate, or other long running commands
do not return output.
sometimes encounter times where a :py:func:`state.apply
<salt.modules.state.apply_>`, or other long running commands do not return
output.
By default the timeout is set to 5 seconds. The timeout value can easily be
increased by modifying the ``timeout`` line within your ``/etc/salt/master``

22
doc/topics/troubleshooting/minion.rst
View File

@ -71,21 +71,21 @@ check that no additional access control system such as `SELinux`_ or
Using salt-call
===============
The ``salt-call`` command was originally developed for aiding in the development
of new Salt modules. Since then, many applications have been developed for
running any Salt module locally on a minion. These range from the original
intent of salt-call, development assistance, to gathering more verbose output
from calls like :mod:`state.highstate <salt.modules.state.highstate>`.
The ``salt-call`` command was originally developed for aiding in the
development of new Salt modules. Since then, many applications have been
developed for running any Salt module locally on a minion. These range from the
original intent of salt-call (development assistance), to gathering more
verbose output from calls like :mod:`state.apply <salt.modules.state.apply_>`.
When initially creating your state tree, it is generally recommended to invoke
:mod:`state.highstate <salt.modules.state.highstate>` from the minion with
``salt-call``. This displays far more information about the highstate execution
than calling it remotely. For even more verbosity, increase the loglevel with
the same argument as ``salt-minion``:
highstates by running :mod:`state.apply <salt.modules.state.apply_>` directly
from the minion with ``salt-call``, rather than remotely from the master. This
displays far more information about the execution than calling it remotely. For
even more verbosity, increase the loglevel using the ``-l`` argument:
.. code-block:: bash
# salt-call -l debug state.highstate
# salt-call -l debug state.apply
The main difference between using ``salt`` and using ``salt-call`` is that
``salt-call`` is run from the minion, and it only runs the selected function on
@ -148,4 +148,4 @@ salt-minion service.
Modifying the minion timeout value is not required when running commands
from a Salt Master. It is only required when running commands locally on
the minion.
the minion.

30
doc/topics/tutorials/cron.rst
View File

@ -1,32 +1,38 @@
===============================================
Using cron with Salt
===============================================
====================
The Salt Minion can initiate its own highstate using the ``salt-call`` command.
The Salt Minion can initiate its own :ref:`highstate <running-highstate>` using
the ``salt-call`` command.
.. code-block:: bash
$ salt-call state.highstate
$ salt-call state.apply
This will cause the minion to check in with the master and ensure it is in the
correct 'state'.
correct "state".
Use cron to initiate a highstate
================================
If you would like the Salt Minion to regularly check in with the master you can
use the venerable cron to run the ``salt-call`` command.
use cron to run the ``salt-call`` command:
.. code-block:: bash
# PATH=/bin:/sbin:/usr/bin:/usr/sbin
0 0 * * * salt-call state.apply
00 00 * * * salt-call state.highstate
The above cron entry will run a highstate every day at midnight.
The above cron entry will run a :ref:`highstate <running-highstate>` every day
at midnight.
.. note::
Be aware that you may need to ensure the PATH for cron includes any
scripts or commands that need to be executed.
When executing Salt using cron, keep in mind that the default PATH for cron
may not include the path for any scripts or commands used by Salt, and it
may be necessary to set the PATH accordingly in the crontab:
.. code-block:: cron
PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin
0 0 * * * salt-call state.apply

10
doc/topics/tutorials/multimaster_pki.rst
View File

@ -149,10 +149,11 @@ In a case like this, it should be checked, that the verification pubkey
Once the verification is successful, the minion can be started in daemon mode
again.
For the paranoid among us, its also possible to verify the public whenever it
is received from the master. That is, for every single auth-attempt which can be
quite frequent. For example just the start of the minion will force the signature
to be checked 6 times for various things like auth, mine, highstate, etc.
For the paranoid among us, its also possible to verify the publication whenever
it is received from the master. That is, for every single auth-attempt which
can be quite frequent. For example just the start of the minion will force the
signature to be checked 6 times for various things like auth, mine,
:ref:`highstate <running-highstate>`, etc.
If that is desired, enable the setting
@ -162,7 +163,6 @@ If that is desired, enable the setting
always_verify_signature: True
Multiple Masters For A Minion
=============================

15
doc/topics/tutorials/pillar.rst
View File

@ -297,18 +297,13 @@ Ensuring that the right vimrc is sent out to the correct minions.
Setting Pillar Data on the Command Line
=======================================
Pillar data can be set on the command line like so:
Pillar data can be set on the command line when running :py:func:`state.apply
<salt.modules.state.apply_` like so:
.. code-block:: bash
salt '*' state.highstate pillar='{"foo": "bar"}'
The ``state.sls`` command can also be used to set pillar values via the command
line:
.. code-block:: bash
salt '*' state.sls my_sls_file pillar='{"hello": "world"}'
salt '*' state.apply pillar='{"foo": "bar"}'
salt '*' state.apply my_sls_file pillar='{"hello": "world"}'
.. note::
@ -321,7 +316,7 @@ specified list, notice the nested pillar dict:
.. code-block:: bash
salt '*' state.sls edit.vim pillar='{"pkgs": {"vim": "telnet"}}'
salt '*' state.apply edit.vim pillar='{"pkgs": {"vim": "telnet"}}'
.. note::

5
doc/topics/tutorials/preseed_key.rst
View File

@ -63,6 +63,5 @@ You will want to place the minion keys before starting the salt-minion daemon:
/etc/salt/pki/minion/minion.pem
/etc/salt/pki/minion/minion.pub
Once in place, you should be able to start salt-minion and run
``salt-call state.highstate`` or any other salt commands that require master
authentication.
Once in place, you should be able to start salt-minion and run ``salt-call
state.apply`` or any other salt commands that require master authentication.

17
doc/topics/tutorials/quickstart.rst
View File

@ -99,21 +99,20 @@ ensures that the server has the Apache webserver installed.
instance on Debian/Ubuntu it is apache2, on Fedora/RHEL it is httpd
and on Arch it is apache
The only thing left is to provision our minion using salt-call and the
highstate command.
The only thing left is to provision our minion using ``salt-call``.
Salt-call
---------
The salt-call command is used to run module functions locally on a minion
instead of executing them from the master. Normally the salt-call command
checks into the master to retrieve file server and pillar data, but when
running standalone salt-call needs to be instructed to not check the master for
this data:
The salt-call command is used to run remote execution functions locally on a
minion instead of executing them from the master. Normally the salt-call
command checks into the master to retrieve file server and pillar data, but
when running standalone salt-call needs to be instructed to not check the
master for this data:
.. code-block:: bash
salt-call --local state.highstate
salt-call --local state.apply
The ``--local`` flag tells the salt-minion to look for the state tree in the
local file system and not to contact a Salt Master for instructions.
@ -122,7 +121,7 @@ To provide verbose output, use ``-l debug``:
.. code-block:: bash
salt-call --local state.highstate -l debug
salt-call --local state.apply -l debug
The minion first examines the ``top.sls`` file and determines that it is a part
of the group matched by ``*`` glob and that the ``webserver`` SLS should be applied.

4
doc/topics/tutorials/standalone_minion.rst
View File

@ -72,14 +72,14 @@ The declared state can now be executed with:
.. code-block:: bash
salt-call state.highstate
salt-call state.apply
Or the salt-call command can be executed with the ``--local`` flag, this makes
it unnecessary to change the configuration file:
.. code-block:: bash
salt-call state.highstate --local
salt-call state.apply --local
External Pillars
================

15
doc/topics/tutorials/starting_states.rst
View File

@ -538,12 +538,17 @@ Running and debugging salt states.
Once the rules in an SLS are ready, they should be tested to ensure they
work properly. To invoke these rules, simply execute
``salt '*' state.highstate`` on the command line. If you get back only
``salt '*' state.apply`` on the command line. If you get back only
hostnames with a ``:`` after, but no return, chances are there is a problem with
one or more of the sls files. On the minion, use the ``salt-call`` command:
``salt-call state.highstate -l debug`` to examine the output for errors.
This should help troubleshoot the issue. The minions can also be started in
the foreground in debug mode: ``salt-minion -l debug``.
one or more of the sls files. On the minion, use the ``salt-call`` command to
examine the output for errors:
.. code-block:: bash
salt-call state.apply -l debug
This should help troubleshoot the issue. The minion can also be started in the
foreground in debug mode by running ``salt-minion -l debug``.
Next Reading
============

44
doc/topics/tutorials/states_pt1.rst
View File

@ -68,7 +68,7 @@ collection of minion matches is defined; for now simply specify all hosts
.. code-block:: yaml
base:
'os:Fedora':
'G@os:Fedora':
- match: grain
- webserver
@ -125,13 +125,31 @@ Next, let's run the state we created. Open a terminal on the master and run:
.. code-block:: bash
% salt '*' state.highstate
salt '*' state.apply
Our master is instructing all targeted minions to run :func:`state.highstate
<salt.modules.state.highstate>`. When a minion executes a highstate call it
will download the :ref:`top file <states-top>` and attempt to match the
expressions. When it does match an expression the modules listed for it will be
downloaded, compiled, and executed.
Our master is instructing all targeted minions to run :func:`state.apply
<salt.modules.state.apply>`. When this function is executied without any SLS
targets, a minion will download the :ref:`top file <states-top>` and attempt to
match the expressions within it. When the minion does match an expression the
modules listed for it will be downloaded, compiled, and executed.
.. note::
This action is referred to as a "highstate", and can be run using the
:py:func:`state.highstate <salt.modules.state.highstate>` function.
However, to make the usage easier to understand ("highstate" is not
necessarily an intuitive name), a :py:func:`state.apply
<salt.modules.state.apply_>` function was added in version 2015.5.0, which
when invoked without any SLS names will trigger a highstate.
:py:func:`state.highstate <salt.modules.state.highstate>` still exists and
can be used, but the documentation (as can be seen above) has been updated
to reference :py:func:`state.apply <salt.modules.state.apply_>`, so keep
the following in mind as you read the documentation:
- :py:func:`state.apply <salt.modules.state.apply_>` invoked without any
SLS names will run :py:func:`state.highstate
<salt.modules.state.highstate>`
- :py:func:`state.apply <salt.modules.state.apply_>` invoked with SLS names
will run :py:func:`state.sls <salt.modules.state.sls>`
Once completed, the minion will report back with a summary of all actions taken
and all changes made.
@ -141,9 +159,9 @@ and all changes made.
If you have created :ref:`custom grain modules <writing-grains>`, they will
not be available in the top file until after the first :ref:`highstate
<running-highstate>`. To make custom grains available on a minion's first
highstate, it is recommended to use :ref:`this example
<minion-start-reactor>` to ensure that the custom grains are synced when
the minion starts.
:ref:`highstate <running-highstate>`, it is recommended to use :ref:`this
example <minion-start-reactor>` to ensure that the custom grains are synced
when the minion starts.
.. _sls-file-namespace:
.. admonition:: SLS File Namespace
@ -190,7 +208,7 @@ and all changes made.
.. code-block:: bash
salt-minion &
salt-minion
Increase the default timeout value when running :command:`salt`. For
example, to change the default timeout to 60 seconds:
@ -203,8 +221,8 @@ and all changes made.
.. code-block:: bash
salt-minion -l debug & # On the minion
salt '*' state.highstate -t 60 # On the master
salt-minion -l debug # On the minion
salt '*' state.apply -t 60 # On the master
Next steps
==========

12
doc/topics/tutorials/states_pt2.rst
View File

@ -28,8 +28,8 @@ You can specify multiple :ref:`state-declaration` under an
- require:
- pkg: apache
Try stopping Apache before running ``state.highstate`` once again and observe
the output.
Try stopping Apache before running :py:func:`state.apply
<salt.modules.state.apply_>` once again and observe the output.
.. note::
@ -101,13 +101,13 @@ directory:
</body>
</html>
Last, call :func:`state.highstate <salt.modules.state.highstate>` again and the
minion will fetch and execute the highstate as well as our HTML file from the
master using Salt's File Server:
Last, call :func:`state.apply <salt.modules.state.apply_>` again and the minion
will fetch and execute the :ref:`highstate <running-highstate>` as well as our
HTML file from the master using Salt's File Server:
.. code-block:: bash
salt '*' state.highstate
salt '*' state.apply
Verify that Apache is now serving your custom HTML.

15
doc/topics/tutorials/states_pt4.rst
View File

@ -153,20 +153,21 @@ Given the above SLS, the source for the website should initially be placed in
``/srv/salt/dev/webserver/src/foobarcom``.
First, let's deploy to dev. Given the configuration in the top file, this can
be done using :mod:`state.highstate <salt.modules.state.highstate>`:
be done using :py:func:`state.apply <salt.modules.state.apply_>`:
.. code-block:: bash
salt --pillar 'webserver_role:dev' state.highstate
salt --pillar 'webserver_role:dev' state.apply
However, in the event that it is not desirable to apply all states configured
in the top file (which could be likely in more complex setups), it is possible
to apply just the states for the ``foobarcom`` website, using :mod:`state.sls
<salt.modules.state.sls>`:
to apply just the states for the ``foobarcom`` website, by invoking
:py:func:`state.apply <salt.modules.state.apply_>` with the desired SLS target
as an argument:
.. code-block:: bash
salt --pillar 'webserver_role:dev' state.sls webserver.foobarcom
salt --pillar 'webserver_role:dev' state.apply webserver.foobarcom
Once the site has been tested in dev, then the files can be moved from
``/srv/salt/dev/webserver/src/foobarcom`` to
@ -174,7 +175,7 @@ Once the site has been tested in dev, then the files can be moved from
.. code-block:: bash
salt --pillar 'webserver_role:qa' state.sls webserver.foobarcom
salt --pillar 'webserver_role:qa' state.apply webserver.foobarcom
Finally, once the site has been tested in qa, then the files can be moved from
``/srv/salt/qa/webserver/src/foobarcom`` to
@ -182,7 +183,7 @@ Finally, once the site has been tested in qa, then the files can be moved from
.. code-block:: bash
salt --pillar 'webserver_role:prod' state.sls webserver.foobarcom
salt --pillar 'webserver_role:prod' state.apply webserver.foobarcom
Thanks to Salt's fileserver inheritance, even though the files have been moved
to within ``/srv/salt/prod``, they are still available from the same

38
doc/topics/tutorials/states_pt5.rst
View File

@ -35,31 +35,32 @@ The Orchestrate Runner
2015.8.0.
The orchestrate runner generalizes the Salt state system to a Salt master
context. Whereas the ``state.sls``, ``state.highstate``, et al functions are
context. Whereas :py:func:`state.apply <salt.modules.state.apply_>` is
concurrently and independently executed on each Salt minion, the
``state.orchestrate`` runner is executed on the master, giving it a
master-level view and control over requisites, such as state ordering and
conditionals. This allows for inter minion requisites, like ordering the
application of states on different minions that must not happen simultaneously,
or for halting the state run on all minions if a minion fails one of its
states.
:py:func:`state.orchestrate <salt.runners.state.orchestrate>` runner is
executed on the master, giving it a master-level view and control over
requisites, such as state ordering and conditionals. This allows for inter
minion requisites, like ordering the application of states on different minions
that must not happen simultaneously, or for halting the state run on all
minions if a minion fails one of its states.
If you want to setup a load balancer in front of a cluster of web servers, for
example, you can ensure the load balancer is setup before the web servers or
stop the state run altogether if one of the minions does not set up correctly.
The ``state.sls``, ``state.highstate``, et al functions allow you to statefully
manage each minion and the ``state.orchestrate`` runner allows you to
statefully manage your entire infrastructure.
:py:func:`state.apply <salt.modules.state.apply_>` allows you to statefully
manage each minion and the :py:func:`state.orchestrate
<salt.runners.state.orchestrate>` runner allows you to statefully manage your
entire infrastructure.
Executing the Orchestrate Runner
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Orchestrate Runner command format is the same as for the ``state.sls``
function, except that since it is a runner, it is executed with ``salt-run``
rather than ``salt``. Assuming you have a state.sls file called
``/srv/salt/orch/webserver.sls`` the following command run on the master will
apply the states defined in that file.
The Orchestrate Runner command format is the same as for the
:py:func:`state.sls <salt.modules.state.sls>` function, except that since it is
a runner, it is executed with ``salt-run`` rather than ``salt``. Assuming you
have a state.sls file called ``/srv/salt/orch/webserver.sls`` the following
command run on the master will apply the states defined in that file.
.. code-block:: bash
@ -72,8 +73,8 @@ apply the states defined in that file.
.. versionchanged:: 2014.1.1
The runner function was renamed to ``state.orchestrate`` to avoid confusion
with the :mod:`state.sls <salt.modules.state.sls>` execution function. In
versions 0.17.0 through 2014.1.0, ``state.sls`` must be used.
with the :mod:`state.sls <salt.modules.state.sls>` remote execution
function. In versions 0.17.0 through 2014.1.0, ``state.sls`` must be used.
Examples
~~~~~~~~
@ -117,7 +118,8 @@ To execute a state, use :mod:`salt.state <salt.states.saltmod.state>`.
Highstate
^^^^^^^^^
To run a highstate, set ``highstate: True`` in your state config:
To run a :ref:`highstate <running-highstate>`, set ``highstate: True`` in your
state config:
.. code-block:: yaml

13
doc/topics/tutorials/walkthrough.rst
View File

@ -510,7 +510,7 @@ Now install vim on the minions by calling the SLS directly:
.. code-block:: bash
salt '*' state.sls vim
salt '*' state.apply vim
This command will invoke the state system and run the ``vim`` SLS.
@ -586,14 +586,13 @@ This formula can be referenced via the following command:
.. code-block:: bash
salt '*' state.sls nginx
salt '*' state.apply nginx
.. note::
Reminder!
Just as one could call the ``test.ping`` or ``disk.usage`` execution modules,
``state.sls`` is simply another execution module. It simply takes the name of an
SLS file as an argument.
:py:func:`state.apply <salt.modules.state.apply_>` is just another remote
execution function, just like :py:func:`test.ping <salt.modules.test.ping>`
or :py:func:`disk.usage <salt.modules.disk.usage>`. It simply takes the
name of an SLS file as an argument.
Now that subdirectories can be used, the ``vim.sls`` formula can be cleaned up.
To make things more flexible, move the ``vim.sls`` and vimrc into a new subdirectory

25
doc/topics/tutorials/walkthrough_macosx.rst
View File

@ -428,10 +428,10 @@ error saying the site cannot be reached.
Initialize the top.sls file
---------------------------
System configuration is done in the /srv/salt/top.sls file (and
subfiles/folders), and then applied by running the ``state.highstate``
command to have the Salt master give orders so minions will update their
instructions and run the associated commands.
System configuration is done in ``/srv/salt/top.sls`` (and subfiles/folders),
and then applied by running the :py:func:`state.apply
<salt.modules.state.apply_>` function to have the Salt master order its minions
to update their instructions and run the associated commands.
First Create an empty file on your Salt master (Mac OS X machine):
@ -444,10 +444,10 @@ an error is reported:
.. code-block:: bash
sudo salt 'minion1' state.highstate
sudo salt 'minion1' state.apply
Should return an error stating:
"No Top file or external nodes data matches found".
This should return an error stating: **No Top file or external nodes data
matches found**.
Create The Nginx Configuration
------------------------------
@ -456,8 +456,8 @@ Now is finally the time to enter the real meat of our server's configuration.
For this tutorial our minion will be treated as a web server that needs to
have Nginx installed.
Insert the following lines into the ``/srv/salt/top.sls`` file (which should
current be empty).
Insert the following lines into ``/srv/salt/top.sls`` (which should current be
empty).
.. code-block:: yaml
@ -465,7 +465,7 @@ current be empty).
'minion1':
- bin.nginx
Now create a ``/srv/salt/bin/nginx.sls`` file containing the following:
Now create ``/srv/salt/bin/nginx.sls`` containing the following:
.. code-block:: yaml
@ -479,11 +479,12 @@ Now create a ``/srv/salt/bin/nginx.sls`` file containing the following:
Check Minion State
------------------
Finally run the state.highstate command again:
Finally, run the :py:func:`state.apply <salt.modules.state.apply_>` function
again:
.. code-block:: bash
sudo salt 'minion1' state.highstate
sudo salt 'minion1' state.apply
You should see a log showing that the Nginx package has been installed
and the service configured. To prove it, open your browser and navigate to

59
salt/config.py
View File

@ -63,7 +63,7 @@ FLO_DIR = os.path.join(
VALID_OPTS = {
# The address of the salt master. May be specified as IP address or hostname
'master': str,
'master': (str, list),
# The TCP/UDP port of the master to connect to in order to listen to publications
'master_port': int,
@ -1348,26 +1348,30 @@ def _validate_opts(opts):
Check that all of the types of values passed into the config are
of the right types
'''
def format_multi_opt(valid_type):
try:
num_types = len(valid_type)
except TypeError:
# Bare type name won't have a length, return the name of the type
# passed.
return valid_type.__name__
else:
if num_types == 1:
return valid_type.__name__
elif num_types > 1:
ret = ', '.join(x.__name__ for x in valid_type[:-1])
ret += ' or ' + valid_type[-1].__name__
errors = []
err = ('Key {0} with value {1} has an invalid type of {2}, a {3} is '
err = ('Key \'{0}\' with value {1} has an invalid type of {2}, a {3} is '
'required for this value')
for key, val in six.iteritems(opts):
if key in VALID_OPTS:
if isinstance(VALID_OPTS[key](), list):
if isinstance(val, VALID_OPTS[key]):
continue
else:
errors.append(
err.format(key, val, type(val).__name__, 'list')
)
if isinstance(VALID_OPTS[key](), dict):
if isinstance(val, VALID_OPTS[key]):
continue
else:
errors.append(
err.format(key, val, type(val).__name__, 'dict')
)
else:
if isinstance(val, VALID_OPTS[key]):
continue
if hasattr(VALID_OPTS[key], '__call__'):
try:
VALID_OPTS[key](val)
if isinstance(val, (list, dict)):
@ -1384,14 +1388,21 @@ def _validate_opts(opts):
VALID_OPTS[key].__name__
)
)
except ValueError:
except (TypeError, ValueError):
errors.append(
err.format(key, val, type(val).__name__, VALID_OPTS[key])
)
except TypeError:
errors.append(
err.format(key, val, type(val).__name__, VALID_OPTS[key])
err.format(key,
val,
type(val).__name__,
VALID_OPTS[key].__name__)
)
continue
errors.append(
err.format(key,
val,
type(val).__name__,
format_multi_opt(VALID_OPTS[key].__name__))
)
# RAET on Windows uses 'win32file.CreateMailslot()' for IPC. Due to this,
# sock_dirs must start with '\\.\mailslot\' and not contain any colons.
@ -1404,7 +1415,7 @@ def _validate_opts(opts):
'\\\\.\\mailslot\\' + opts['sock_dir'].replace(':', ''))
for error in errors:
log.warning(error)
log.debug(error)
if errors:
return False
return True

237
salt/modules/state.py
View File

@ -106,9 +106,9 @@ def _wait(jid):
def running(concurrent=False):
'''
Return a list of strings that contain state return data if a state function is
already running. This function is used to prevent multiple state calls from being
run at the same time.
Return a list of strings that contain state return data if a state function
is already running. This function is used to prevent multiple state calls
from being run at the same time.
CLI Example:
@ -175,7 +175,9 @@ def _get_opts(localconfig=None):
def low(data, queue=False, **kwargs):
'''
Execute a single low data call
This function is mostly intended for testing the state system
This function is mostly intended for testing the state system and is not
likely to be needed in everyday usage.
CLI Example:
@ -205,7 +207,9 @@ def low(data, queue=False, **kwargs):
def high(data, test=False, queue=False, **kwargs):
'''
Execute the compound calls stored in a single set of high data
This function is mostly intended for testing the state system
This function is mostly intended for testing the state system andis not
likely to be needed in everyday usage.
CLI Example:
@ -307,17 +311,127 @@ def apply_(mods=None,
'''
.. versionadded:: 2015.5.0
Apply states! This function will call highstate or state.sls based on the
arguments passed in, state.apply is intended to be the main gateway for
all state executions.
This function will call :mod:`state.highstate
<salt.modules.state.highstate>` or :mod:`state.sls
<salt.modules.state.sls>` based on the arguments passed to this function.
It exists as a more intuitive way of applying states.
CLI Example:
.. rubric:: APPLYING ALL STATES CONFIGURED IN TOP.SLS (A.K.A. :ref:`HIGHSTATE <running-highstate>`)
To apply all configured states, simply run ``state.apply``:
.. code-block:: bash
salt '*' state.apply
The following additional arguments are also accepted when applying all
states configured in top.sls:
test
Run states in test-only (dry-run) mode
pillar
Custom Pillar values, passed as a dictionary of key-value pairs
.. code-block:: bash
salt '*' state.apply test pillar='{"foo": "bar"}'
.. note::
Values passed this way will override Pillar values set via
``pillar_roots`` or an external Pillar source.
queue : False
Instead of failing immediately when another state run is in progress,
queue the new state run to begin running once the other has finished.
This option starts a new thread for each queued state run, so use this
option sparingly.
localconfig
Optionally, instead of using the minion config, load minion opts from
the file specified by this argument, and then merge them with the
options from the minion config. This functionality allows for specific
states to be run with their own custom minion configuration, including
different pillars, file_roots, etc.
.. code-block:: bash
salt '*' state.apply localconfig=/path/to/minion.yml
.. rubric:: APPLYING INDIVIDUAL SLS FILES (A.K.A. :py:func:`STATE.SLS <salt.modules.state.sls>`)
To apply individual SLS files, pass them as a comma-separated list:
.. code-block:: bash
# Run the states configured in salt://test.sls (or salt://test/init.sls)
salt '*' state.apply test
# Run the states configured in salt://test.sls (or salt://test/init.sls)
# and salt://pkgs.sls (or salt://pkgs/init.sls).
salt '*' state.apply test,pkgs
The following additional arguments are also accepted when applying
individual SLS files:
test
Run states in test-only (dry-run) mode
pillar
Custom Pillar values, passed as a dictionary of key-value pairs
.. code-block:: bash
salt '*' state.apply test pillar='{"foo": "bar"}'
.. note::
Values passed this way will override Pillar values set via
``pillar_roots`` or an external Pillar source.
queue : False
Instead of failing immediately when another state run is in progress,
queue the new state run to begin running once the other has finished.
This option starts a new thread for each queued state run, so use this
option sparingly.
concurrent : False
Execute state runs concurrently instead of serially
.. warning::
This flag is potentially dangerous. It is designed for use when
multiple state runs can safely be run at the same time. Do *not*
use this flag for performance optimization.
saltenv : None
Specify a salt fileserver environment to be used when applying states
.. versionchanged:: 0.17.0
Argument name changed from ``env`` to ``saltenv``
.. versionchanged:: 2014.7.0
If no saltenv is specified, the minion config will be checked for a
``saltenv`` parameter and if found, it will be used. If none is
found, ``base`` will be used. In prior releases, the minion config
was not checked and ``base`` would always be assumed when the
saltenv was not explicitly set.
pillarenv
Specify a Pillar environment to be used when applying states. By
default, all Pillar environments will be merged together and used.
localconfig
Optionally, instead of using the minion config, load minion opts from
the file specified by this argument, and then merge them with the
options from the minion config. This functionality allows for specific
states to be run with their own custom minion configuration, including
different pillars, file_roots, etc.
.. code-block:: bash
salt '*' state.apply test localconfig=/path/to/minion.yml
'''
if mods:
return sls(mods, **kwargs)
@ -468,24 +582,32 @@ def highstate(test=None,
Retrieve the state data from the salt master for this minion and execute it
test
Notify states to execute in test-only (dry-run) mode.
Run states in test-only (dry-run) mode
Sets the ``test`` variable in the minion ``opts`` for the duration of
the state run.
pillar
Custom Pillar data can be passed with the ``pillar`` kwarg. Values
passed here will override hard-coded Pillar values.
queue : ``False``
Custom Pillar values, passed as a dictionary of key-value pairs
.. code-block:: bash
salt '*' state.apply test pillar='{"foo": "bar"}'
.. note::
Values passed this way will override Pillar values set via
``pillar_roots`` or an external Pillar source.
queue : False
Instead of failing immediately when another state run is in progress,
queue the new state run to begin running once the other has finished.
This option starts a new thread for each queued state run so use this
This option starts a new thread for each queued state run, so use this
option sparingly.
localconfig:
Instead of using running minion opts, load ``localconfig`` and merge that
with the running minion opts. This functionality is intended for using
"roots" of salt directories (with their own minion config, pillars,
file_roots) to run highstate out of.
localconfig
Optionally, instead of using the minion config, load minion opts from
the file specified by this argument, and then merge them with the
options from the minion config. This functionality allows for specific
states to be run with their own custom minion configuration, including
different pillars, file_roots, etc.
mock:
The mock option allows for the state run to execute without actually
@ -494,7 +616,7 @@ def highstate(test=None,
.. versionadded:: 2015.8.4
CLI Example:
CLI Examples:
.. code-block:: bash
@ -595,43 +717,62 @@ def sls(mods,
pillarenv=None,
**kwargs):
'''
Execute a set list of state files from an environment.
Execute the states in one or more SLS files
test
Notify states to execute in test-only (dry-run) mode.
Run states in test-only (dry-run) mode
Sets the ``test`` variable in the minion ``opts`` for the duration of
the state run.
pillar
Custom Pillar data can be passed with the ``pillar`` kwarg. Values
passed here will override hard-coded Pillar values.
queue : ``False``
Custom Pillar values, passed as a dictionary of key-value pairs
.. code-block:: bash
salt '*' state.apply test pillar='{"foo": "bar"}'
.. note::
Values passed this way will override Pillar values set via
``pillar_roots`` or an external Pillar source.
queue : False
Instead of failing immediately when another state run is in progress,
queue the new state run to begin running once the other has finished.
This option starts a new thread for each queued state run so use this
This option starts a new thread for each queued state run, so use this
option sparingly.
concurrent : False
Execute state runs concurrently instead of serially
.. warning::
This flag is potentially dangerous. It is designed for use when
multiple state runs can safely be run at the same time. Do *not*
use this flag for performance optimization.
saltenv : None
Specify a ``file_roots`` environment.
Specify a salt fileserver environment to be used when applying states
.. versionchanged:: 0.17.0
Argument name changed from ``env`` to ``saltenv``.
.. versionchanged:: 2014.7
Defaults to None. If no saltenv is specified, the minion config will
be checked for a saltenv and if found, it will be used. If none is found,
base will be used.
pillarenv : None
Specify a ``pillar_roots`` environment. By default all pillar environments
merged together will be used.
concurrent:
WARNING: This flag is potentially dangerous. It is designed
for use when multiple state runs can safely be run at the same
Do not use this flag for performance optimization.
localconfig:
Instead of using running minion opts, load ``localconfig`` and merge that
with the running minion opts. This functionality is intended for using
"roots" of salt directories (with their own minion config, pillars,
file_roots) to run highstate out of.
Argument name changed from ``env`` to ``saltenv``
.. versionchanged:: 2014.7.0
If no saltenv is specified, the minion config will be checked for a
``saltenv`` parameter and if found, it will be used. If none is
found, ``base`` will be used. In prior releases, the minion config
was not checked and ``base`` would always be assumed when the
saltenv was not explicitly set.
pillarenv
Specify a Pillar environment to be used when applying states. By
default, all Pillar environments will be merged together and used.
localconfig
Optionally, instead of using the minion config, load minion opts from
the file specified by this argument, and then merge them with the
options from the minion config. This functionality allows for specific
states to be run with their own custom minion configuration, including
different pillars, file_roots, etc.
mock:
The mock option allows for the state run to execute without actually

39
salt/states/grains.py
View File

@ -226,27 +226,36 @@ def list_absent(name, value, delimiter=DEFAULT_TARGET_DELIM):
'changes': {},
'result': True,
'comment': ''}
comments = []
grain = __salt__['grains.get'](name, None)
if grain:
if isinstance(grain, list):
if value not in grain:
ret['comment'] = 'Value {1} is absent from grain {0}' \
.format(name, value)
return ret
if __opts__['test']:
ret['result'] = None
ret['comment'] = 'Value {1} in grain {0} is set to ' \
'be deleted'.format(name, value)
ret['changes'] = {'deleted': value}
return ret
__salt__['grains.remove'](name, value)
ret['comment'] = 'Value {1} was deleted from grain {0}'\
.format(name, value)
ret['changes'] = {'deleted': value}
if not isinstance(value, list):
value = [value]
for val in value:
if val not in grain:
comments.append('Value {1} is absent from '
'grain {0}'.format(name, val))
elif __opts__['test']:
ret['result'] = None
comments.append('Value {1} in grain {0} is set '
'to be deleted'.format(name, val))
if 'deleted' not in ret['changes'].keys():
ret['changes'] = {'deleted': []}
ret['changes']['deleted'].append(val)
elif val in grain:
__salt__['grains.remove'](name, val)
comments.append('Value {1} was deleted from '
'grain {0}'.format(name, val))
if 'deleted' not in ret['changes'].keys():
ret['changes'] = {'deleted': []}
ret['changes']['deleted'].append(val)
ret['comment'] = '\n'.join(comments)
return ret
else:
ret['result'] = False
ret['comment'] = 'Grain {0} is not a valid list'\
.format(name)
.format(name)
else:
ret['comment'] = 'Grain {0} does not exist'.format(name)
return ret

1
tests/integration/modules/sysmod.py
View File

@ -72,6 +72,7 @@ class SysModuleTest(integration.ModuleCase):
'nspawn.stop',
'nspawn.restart',
'lowpkg.bin_pkg_info',
'state.apply',
)
for fun in docs: