salt/doc/topics/releases/0.9.4.rst

========================
Salt 0.9.4 Release Notes
========================

Salt 0.9.4 has arrived. This is a critical update that repairs a number of
key bugs found in 0.9.3. But this update is not without feature additions
as well! 0.9.4 adds support for Gentoo portage to the pkg module and state
system. Also there are 2 major new state additions, the failhard option and
the ability to set up finite state ordering with the ``order`` option.

This release also sees our largest increase in community contributions.
These contributors have and continue to be the life blood of the Salt
project, and the team continues to grow. I want to put out a big thanks to
our new and existing contributors.

Download!
=========

The Salt source can be downloaded from the salt github site:

:download:`salt-0.9.4.tar.gz`

Or from PiPy:

http://pypi.python.org/packages/source/s/salt/salt-0.9.4.tar.gz

For instructions on how to set up Salt please see the :ref:`installation`
instructions.

New Features
============

Failhard State Option
---------------------

Normally, when a state fails Salt continues to execute the remainder of the
defined states and will only refuse to execute states that require the failed
state.

But the situation may exist, where you would want all state execution to stop
if a single state execution fails. The capability to do this is called
``failing hard``.

State Level Failhard
````````````````````

A single state can have a failhard set, this means that if this individual
state fails that all state execution will immediately stop. This is a great
thing to do if there is a state that sets up a critical config file and
setting a require for each state that reads the config would be cumbersome.
A good example of this would be setting up a package manager early on:

.. code-block:: yaml

    /etc/yum.repos.d/company.repo:
      file:
        - managed
        - source: salt://company/yumrepo.conf
        - user: root
        - group: root
        - mode: 644
        - order: 1
        - failhard: True

In this situation, the yum repo is going to be configured before other states,
and if it fails to lay down the config file, than no other states will be
executed.

Global Failhard
```````````````

It may be desired to have failhard be applied to every state that is executed,
if this is the case, then failhard can be set in the master configuration
file. Setting failhard in the master configuration file will result in failing
hard when any minion gathering states from the master have a state fail.

This is NOT the default behavior, normally Salt will only fail states that
require a failed state.

Using the global failhard is generally not recommended, since it can result
in states not being executed or even checked. It can also be confusing to
see states failhard if an admin is not actively aware that the failhard has
been set.

To use the global failhard set failhard: True in the master configuration

Finite Ordering of State Execution
----------------------------------

When creating salt sls files, it is often important to ensure that they run in
a specific order. While states will always execute in the same order, that
order is not necessarily defined the way you want it.

A few tools exist in Salt to set up the correct state ordering, these tools
consist of requisite declarations and order options.

The Order Option
````````````````

Before using the order option, remember that the majority of state ordering
should be done with requisite statements, and that a requisite statement
will override an order option.

The order option is used by adding an order number to a state declaration
with the option `order`:

.. code-block:: yaml

    vim:
      pkg:
        - installed
        - order: 1

By adding the order option to `1` this ensures that the vim package will be
installed in tandem with any other state declaration set to the order `1`.

Any state declared without an order option will be executed after all states
with order options are executed.

But this construct can only handle ordering states from the beginning.
Sometimes you may want to send a state to the end of the line, to do this
set the order to last:

.. code-block:: yaml

    vim:
      pkg:
        - installed
        - order: last

Substantial testing has gone into the state system and it is ready for real
world usage. A great deal has been added to the documentation for states and
the modules and functions available to states have been cleanly documented.

A number of State System bugs have also been founds and repaired, the output
from the state system has also been refined to be extremely clear and concise.

Error reporting has also been introduced, issues found in sls files will now
be clearly reported when executing Salt States.

                      
Gentoo Support
--------------

Additional experimental support has been added for Gentoo. This is found in
the contribution from Doug Renn, aka nestegg.