diff --git a/doc/faq.rst b/doc/faq.rst index c0f858af6d..282f82e5b6 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -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 ` rather than :mod:`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 -`, :mod:`saltutil.sync_modules +Custom modules are only synced to Minions when :mod:`state.apply +`, :mod:`saltutil.sync_modules `, or :mod:`saltutil.sync_all ` is run. Similarly, custom states are only -synced to Minions when :mod:`state.highstate `, +synced to Minions when :mod:`state.apply `, :mod:`saltutil.sync_states `, or :mod:`saltutil.sync_all ` is run. diff --git a/doc/ref/configuration/minion.rst b/doc/ref/configuration/minion.rst index cafdc4fd4e..866107ea66 100644 --- a/doc/ref/configuration/minion.rst +++ b/doc/ref/configuration/minion.rst @@ -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 ` is called. .. conf_minion:: cache_jobs diff --git a/doc/ref/modules/index.rst b/doc/ref/modules/index.rst index aa398d5d48..1bcb104c25 100644 --- a/doc/ref/modules/index.rst +++ b/doc/ref/modules/index.rst @@ -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 ` +* :mod:`state.apply ` * :mod:`saltutil.sync_modules ` * :mod:`saltutil.sync_all ` diff --git a/doc/ref/renderers/index.rst b/doc/ref/renderers/index.rst index 5cbfbd94c9..9620118df6 100644 --- a/doc/ref/renderers/index.rst +++ b/doc/ref/renderers/index.rst @@ -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 ` - :mod:`saltutil.sync_renderers ` - - :mod:`saltutil.sync_all ` +- :py:func:`state.apply ` +- :py:func:`saltutil.sync_renderers ` +- :py:func:`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 diff --git a/doc/ref/returners/index.rst b/doc/ref/returners/index.rst index 66ed0c7201..985388918f 100644 --- a/doc/ref/returners/index.rst +++ b/doc/ref/returners/index.rst @@ -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 ` - :mod:`saltutil.sync_returners ` - - :mod:`saltutil.sync_all ` +- :mod:`state.apply ` +- :mod:`saltutil.sync_returners ` +- :mod:`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 diff --git a/doc/ref/states/compiler_ordering.rst b/doc/ref/states/compiler_ordering.rst index b71058236d..743204a50b 100644 --- a/doc/ref/states/compiler_ordering.rst +++ b/doc/ref/states/compiler_ordering.rst @@ -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 diff --git a/doc/ref/states/highstate.rst b/doc/ref/states/highstate.rst index 5c3bb2df54..2d308b7952 100644 --- a/doc/ref/states/highstate.rst +++ b/doc/ref/states/highstate.rst @@ -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 ` 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: diff --git a/doc/ref/states/include.rst b/doc/ref/states/include.rst index 22c72f988b..950e48206c 100644 --- a/doc/ref/states/include.rst +++ b/doc/ref/states/include.rst @@ -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 ` 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``. + diff --git a/doc/ref/states/index.rst b/doc/ref/states/index.rst index de3b3e21f1..e602b39960 100644 --- a/doc/ref/states/index.rst +++ b/doc/ref/states/index.rst @@ -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: diff --git a/doc/ref/states/layers.rst b/doc/ref/states/layers.rst index 1f027ff00f..47102b2729 100644 --- a/doc/ref/states/layers.rst +++ b/doc/ref/states/layers.rst @@ -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 `, 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 +` 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 ` use :py:func:`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. \ No newline at end of file +requisite logic. diff --git a/doc/ref/states/startup.rst b/doc/ref/states/startup.rst index c0b150ced6..581907571d 100644 --- a/doc/ref/states/startup.rst +++ b/doc/ref/states/startup.rst @@ -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 ` + Execute :py:func:`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 ` to run the +:ref:`highstate ` when starting the minion: .. code-block:: yaml diff --git a/doc/ref/states/testing.rst b/doc/ref/states/testing.rst index 4387fcbd64..c967f88ef3 100644 --- a/doc/ref/states/testing.rst +++ b/doc/ref/states/testing.rst @@ -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 \ No newline at end of file + salt '*' state.apply test=False + salt '*' state.apply mysls test=False + salt '*' state.single test=False diff --git a/doc/ref/states/writing.rst b/doc/ref/states/writing.rst index cc70b190f5..985487523d 100644 --- a/doc/ref/states/writing.rst +++ b/doc/ref/states/writing.rst @@ -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 ` is -run, or by executing the :mod:`saltutil.sync_states +are distributed when :py:func:`state.apply ` is run, +or by executing the :mod:`saltutil.sync_states ` or :mod:`saltutil.sync_all ` functions. diff --git a/doc/topics/cloud/deploy.rst b/doc/topics/cloud/deploy.rst index 251def42e5..fc07009bcb 100644 --- a/doc/topics/cloud/deploy.rst +++ b/doc/topics/cloud/deploy.rst @@ -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 `, +which would finish provisioning the VM. Another common option (for testing) is +to use :py:func:`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 diff --git a/doc/topics/cloud/reactor.rst b/doc/topics/cloud/reactor.rst index 096a41d264..9b026c4517 100644 --- a/doc/topics/cloud/reactor.rst +++ b/doc/topics/cloud/reactor.rst @@ -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 +`, 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 ` 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 ` 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 +` 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 ` 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. diff --git a/doc/topics/development/conventions/formulas.rst b/doc/topics/development/conventions/formulas.rst index ce9c92ccfc..88cc206e95 100644 --- a/doc/topics/development/conventions/formulas.rst +++ b/doc/topics/development/conventions/formulas.rst @@ -367,7 +367,8 @@ variables or interact. for :ref:`any of the alternate 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 ` 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 ` 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 ` and checking the output for +the success or failure of each state in the Formula. This should be done for +each supported platform. .. ............................................................................ diff --git a/doc/topics/development/dunder_dictionaries.rst b/doc/topics/development/dunder_dictionaries.rst index e9860db0e8..17b807d78e 100644 --- a/doc/topics/development/dunder_dictionaries.rst +++ b/doc/topics/development/dunder_dictionaries.rst @@ -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 ` or +:py:func:`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. \ No newline at end of file + generate the key before using it. diff --git a/doc/topics/jobs/schedule.rst b/doc/topics/jobs/schedule.rst index 52df887aaa..de7953009a 100644 --- a/doc/topics/jobs/schedule.rst +++ b/doc/topics/jobs/schedule.rst @@ -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 ` 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. diff --git a/doc/topics/master_tops/index.rst b/doc/topics/master_tops/index.rst index 12a5ddcb23..60df4b4723 100644 --- a/doc/topics/master_tops/index.rst +++ b/doc/topics/master_tops/index.rst @@ -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 +` 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 \ No newline at end of file + - test diff --git a/doc/topics/pillar/index.rst b/doc/topics/pillar/index.rst index 80118b7e6d..386528549f 100644 --- a/doc/topics/pillar/index.rst +++ b/doc/topics/pillar/index.rst @@ -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:: diff --git a/doc/topics/reactor/index.rst b/doc/topics/reactor/index.rst index 4a7fe2e335..81f3180db9 100644 --- a/doc/topics/reactor/index.rst +++ b/doc/topics/reactor/index.rst @@ -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 +`. 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 ` 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 ` +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 +` 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 ` documentation -for that. +The above will also return the :ref:`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 +` 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 -`) 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. +`) on every :ref:`highstate +`. However, there is a chicken-and-egg issue where, on the +initial :ref:`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 +` 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 diff --git a/doc/topics/releases/2015.5.10.rst b/doc/topics/releases/2015.5.10.rst index 49a5598140..a6f158d9c9 100644 --- a/doc/topics/releases/2015.5.10.rst +++ b/doc/topics/releases/2015.5.10.rst @@ -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. + diff --git a/doc/topics/targeting/grains.rst b/doc/topics/targeting/grains.rst index 0be990e3c0..ea03ab05c8 100644 --- a/doc/topics/targeting/grains.rst +++ b/doc/topics/targeting/grains.rst @@ -168,12 +168,11 @@ keys in the :ref:`dict ` 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 -` is run, or by executing the -:mod:`saltutil.sync_grains ` or -:mod:`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 ` is run, or by +executing the :mod:`saltutil.sync_grains ` +or :mod:`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 `. To make custom grains available on a - minion's first highstate, it is recommended to use :ref:`this example - ` to ensure that the custom grains are synced when - the minion starts. + minion's first :ref:`highstate `, it is recommended to + use :ref:`this example ` 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 ` is called, or (as noted -above) the grains can be manually synced and reloaded by calling the +:mod:`state.apply ` is called, or (as noted above) +the grains can be manually synced and reloaded by calling the :mod:`saltutil.sync_grains ` or :mod:`saltutil.sync_all ` functions. diff --git a/doc/topics/troubleshooting/index.rst b/doc/topics/troubleshooting/index.rst index 9b62094b7d..33fd39f20a 100644 --- a/doc/topics/troubleshooting/index.rst +++ b/doc/topics/troubleshooting/index.rst @@ -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 `. +from calls like :mod:`state.apply `. -When creating your state tree, it is generally recommended to invoke -:mod:`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 ` 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` and :doc:`minion` troubleshooting steps provide a -starting point for resolving issues you may encounter. \ No newline at end of file +starting point for resolving issues you may encounter. diff --git a/doc/topics/troubleshooting/master.rst b/doc/topics/troubleshooting/master.rst index 6c37edcb2a..3379a7b9a0 100644 --- a/doc/topics/troubleshooting/master.rst +++ b/doc/topics/troubleshooting/master.rst @@ -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 +`, 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`` diff --git a/doc/topics/troubleshooting/minion.rst b/doc/topics/troubleshooting/minion.rst index d15f559bad..327b210315 100644 --- a/doc/topics/troubleshooting/minion.rst +++ b/doc/topics/troubleshooting/minion.rst @@ -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 `. +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 `. When initially creating your state tree, it is generally recommended to invoke -:mod:`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 ` 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. \ No newline at end of file + the minion. diff --git a/doc/topics/tutorials/cron.rst b/doc/topics/tutorials/cron.rst index 440c2ef707..35231852e5 100644 --- a/doc/topics/tutorials/cron.rst +++ b/doc/topics/tutorials/cron.rst @@ -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 ` 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 ` 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. \ No newline at end of file + 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 diff --git a/doc/topics/tutorials/multimaster_pki.rst b/doc/topics/tutorials/multimaster_pki.rst index 254acf0dbb..175931e9b1 100644 --- a/doc/topics/tutorials/multimaster_pki.rst +++ b/doc/topics/tutorials/multimaster_pki.rst @@ -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 `, 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 ============================= diff --git a/doc/topics/tutorials/pillar.rst b/doc/topics/tutorials/pillar.rst index a67ac1aae1..0af19d631e 100644 --- a/doc/topics/tutorials/pillar.rst +++ b/doc/topics/tutorials/pillar.rst @@ -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 +`. When a minion executes a highstate call it -will download the :ref:`top file ` 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 +`. When this function is executied without any SLS +targets, a minion will download the :ref:`top file ` 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 ` function. + However, to make the usage easier to understand ("highstate" is not + necessarily an intuitive name), a :py:func:`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 ` still exists and + can be used, but the documentation (as can be seen above) has been updated + to reference :py:func:`state.apply `, so keep + the following in mind as you read the documentation: + + - :py:func:`state.apply ` invoked without any + SLS names will run :py:func:`state.highstate + ` + - :py:func:`state.apply ` invoked with SLS names + will run :py:func:`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 `, they will not be available in the top file until after the first :ref:`highstate `. To make custom grains available on a minion's first - highstate, it is recommended to use :ref:`this example - ` to ensure that the custom grains are synced when - the minion starts. + :ref:`highstate `, it is recommended to use :ref:`this + example ` 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 ========== diff --git a/doc/topics/tutorials/states_pt2.rst b/doc/topics/tutorials/states_pt2.rst index 23a1fd8803..cdba7a23af 100644 --- a/doc/topics/tutorials/states_pt2.rst +++ b/doc/topics/tutorials/states_pt2.rst @@ -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 +` once again and observe the output. .. note:: @@ -101,13 +101,13 @@ directory: -Last, call :func:`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 ` again and the minion +will fetch and execute the :ref:`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. diff --git a/doc/topics/tutorials/states_pt4.rst b/doc/topics/tutorials/states_pt4.rst index 40eab99fd5..a18a19d605 100644 --- a/doc/topics/tutorials/states_pt4.rst +++ b/doc/topics/tutorials/states_pt4.rst @@ -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 `: +be done using :py:func:`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 -`: +to apply just the states for the ``foobarcom`` website, by invoking +:py:func:`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 diff --git a/doc/topics/tutorials/states_pt5.rst b/doc/topics/tutorials/states_pt5.rst index 61de0d3254..333e3fafe6 100644 --- a/doc/topics/tutorials/states_pt5.rst +++ b/doc/topics/tutorials/states_pt5.rst @@ -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 ` 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 ` 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 ` allows you to statefully +manage each minion and the :py:func:`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 ` 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 ` execution function. In - versions 0.17.0 through 2014.1.0, ``state.sls`` must be used. + with the :mod:`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 `. Highstate ^^^^^^^^^ -To run a highstate, set ``highstate: True`` in your state config: +To run a :ref:`highstate `, set ``highstate: True`` in your +state config: .. code-block:: yaml diff --git a/doc/topics/tutorials/walkthrough.rst b/doc/topics/tutorials/walkthrough.rst index 908c291bb3..4e9a9da204 100644 --- a/doc/topics/tutorials/walkthrough.rst +++ b/doc/topics/tutorials/walkthrough.rst @@ -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 ` is just another remote + execution function, just like :py:func:`test.ping ` + or :py:func:`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 diff --git a/doc/topics/tutorials/walkthrough_macosx.rst b/doc/topics/tutorials/walkthrough_macosx.rst index 5d9cf7e96c..efb32d0e9d 100644 --- a/doc/topics/tutorials/walkthrough_macosx.rst +++ b/doc/topics/tutorials/walkthrough_macosx.rst @@ -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 +` 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 ` 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 diff --git a/salt/config.py b/salt/config.py index 071e06bb52..1f83c33158 100644 --- a/salt/config.py +++ b/salt/config.py @@ -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 diff --git a/salt/modules/state.py b/salt/modules/state.py index edc1f74487..8a38f1dd09 100644 --- a/salt/modules/state.py +++ b/salt/modules/state.py @@ -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 + ` or :mod:`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 `) + + 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 `) + + 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 diff --git a/salt/states/grains.py b/salt/states/grains.py index 3d66efe2c7..17312dca4e 100644 --- a/salt/states/grains.py +++ b/salt/states/grains.py @@ -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 diff --git a/tests/integration/modules/sysmod.py b/tests/integration/modules/sysmod.py index ef38161850..7f41818747 100644 --- a/tests/integration/modules/sysmod.py +++ b/tests/integration/modules/sysmod.py @@ -72,6 +72,7 @@ class SysModuleTest(integration.ModuleCase): 'nspawn.stop', 'nspawn.restart', 'lowpkg.bin_pkg_info', + 'state.apply', ) for fun in docs: