salt/doc/topics/releases/0.9.8.rst

========================
Salt 0.9.8 Release Notes
========================

Salt 0.9.8 is a big step forward, with many additions and enhancements, as
well as a number of precursors to advanced future developments.

This version of Salt adds much more power to the command line, making the
old hard timeout issues a thing of the past, and adding keyword argument
support to salt calls. These additions are also available in the salt client
api, making the available api tools much more powerful.

The new pillar system allows for data to be stored on the master and
assigned to minions in a granular way similar to the state system.

Additions to requisites making them much more powerful have been added and
improved error checking for sls files in the state system. A new provider
system has been added to allow for redirecting what modules function in
the background for individual states.

Support for OpenSUSE has been added and support for Solaris has begun
serious development. Windows support has been signifigantly enhanced as well.

The matcher and target systems have received a great deal of attention. The
default behavior of grain matching has changed slightly to reflect the salt
default behavior and the compound matcher system has been greatly refined.

A number of impressive features with keyword arguments have been added to both
the cli and to the state system, making states much more powerful and flexible,
but available in a clean and simple way.

The new batch size capability allows for executions to be rolled through the
targeted minions in percentage or specific numbers of minions. This was added
to prevent the "thundering herd" problem when targetting large numbers of
minions for things like service restarts or file downloads.

Upgrade Considerations
======================

Upgrade Issue
-------------

There was an oversight that has been previously missed which could cause a
newer minion to crash an older master. This oversight has been repaired so
that this version incompatibility issue will not occur again. When upgrading
to 0.9.8 make sure to upgrade the master first, followed by the minions.

Debian/Ubuntu Packages
----------------------

The original Debian/Ubuntu packages were called salt and included all salt
applications. New packages in the ppa are split. If an old salt package is
installed then it should be manually removed and the new split packages
need to be installed fresh.


Major Features
==============

Pillar
------

Pillar offers an interface to declare variable data on the master that is then
assigned to the minions. The pillar data is made available to all modules,
states, sls files etc. It is compiled on the master and is declared using the
existing renderer system. This means that learning pillar should be fairly
trivial to those already familiar with salt states.

CLI Additions
-------------

The salt command in 0.9.8 has received a serious overhaul and is more powerful
then ever. Data is returned to the terminal as it is received, and the salt
command will now wait for all running minions to return data before stopping.

Kwargs and States
-----------------

A new addition to writing state modules has been made available. State modules
can now accept the ``**kwargs`` argument. The result of this is that all data
in an sls file assigned to a state will be made available to the state function.

This enables data to be passed in a transparent way back to the modules that
are executing the logic. In particular this allows us to add arguments to the
pkg.install module that enable more advanced and granular controls with respect
to what the state is capable of.

Kwargs and the CLI
------------------

In the past it was required that all arguments be passed in order to modules
from the salt and salt-call commands. As of 0.9.8 keyword arguments can be
passed in the form of ``kwarg=argument``.

Matcher Refinements and Changes
-------------------------------

Support has been added for matching minions with Yahoo's range library. This
is handled by passing range syntax with *-R* or *--range* arguments to salt.

More information at:
https://github.com/grierj/range/wiki/Introduction-to-Range-with-YAML-files

Much like the rest of salt, grains are now matched by default using globs
instead of regular expressions. A new *--grain-pcre* was added to the salt
command line for doing just this:

.. code-block:: sh

  # salt --grain-pcre 'os:(Arch:Fed).*' test.ping

The associated compound matcher for use in states or the ``top.sls`` is *P*:


.. code-block:: sh

  P@os:(Arch|Fed).*

**NOTE**: The default grains matcher has changed from pcre to glob for consistency
=======
A number of fixes and changes have been applied to the Matcher system. The
most noteworthy is the change in the grain matcher. The grain matcher used
a regular expression to match the passed data to a grain, but now defaults
to a shell glob like the majority of match interfaces in Salt. A new option
is available that still uses the old style regex matching to grain data called
grain-pcre. To use regex matching in compound matches use the letter P.

Providers
---------

Salt predetermines what modules should be mapped to what uses based on the
properties of a system. These determinations are generally made for modules
that provide things like package and service management.

Sometimes in states it may be needed for an alternative module to be used
to provide the functionality needed. For instance, an Arch Linux system may
have been set up with systemd support, so instead of using the default service
module detected for Arch Linux, the systemd module can be used:

.. code-block:: yaml

    http:
      service:
        - running
        - enable: True
        - provider: systemd

Requisite Glob Matching
-----------------------

Requisites can now be defined with glob expansion. This means that if there are
many requisities they can be defined in a single line. For instance, if all
files in a directory are required or watched, then it can be defined like so:

.. code-block:: yaml

    http:
      service:
        - running
        - enable: True
        - watch:
          - file: /etc/http/conf.d/*

This example will watch all defined files that match the glob
``/etc/http/conf.d/*``

Batch Size
----------

The new batch size option allows for commands to be executed while maintaining
that only so many hosts are executing the command at one time. This option can
take a percentage or a finite number:

.. code-block:: bash

    salt \* -b %10 test.ping

This will only run test.ping on %10 of targeted systems at a time and work
through all targeted systems until the task is complete


Module Updates
---------------

This is a list of notable, but not complete updates with new and existing
modules.

For our ruby users, new :doc:`rvm </ref/modules/all/salt.modules.rvm>` and
:doc:`gem </ref/modules/all/salt.modules.gem>` modules have been added along
with the :doc:`associated </ref/states/all/salt.states.rvm>`
:doc:`states </ref/states/all/salt.states.gem>`


The :doc:`virt </ref/modules/all/salt.modules.virt>` module gained basic Xen support.

The :doc:`pkg </ref/modules/all/salt.modules.yumpkg>` module gained Scientific Linux support.

The :doc:`pkg </ref/modules/all/salt.modules.apt>` module on Debian, Ubuntu, and derivatives
forces apt to run in a non-interactive mode preventing previous issues with installation. Also,
Ubuntu users gained a new upstart :doc:`service </ref/modules/all/salt.modules.upstart>` module.

The :doc:`mysql.user </ref/states/all/salt.states.mysql_user>` state and :doc:`mysql </ref/modules/all/salt.modules.mysql>` module gained a *password_hash* argument.

The :doc:`cmd </ref/modules/all/salt.modules.cmdmod>` module and state gained a *shell* keyword argument for specifying
a shell other than ``/bin/sh`` on Linux / Unix systems.


In Progress Development
=======================

Master Side State Compiling
---------------------------

While we feel strongly that the advantages gained with minion side state
compiling is very critical, it does prevent certain features what may be
desired. 0.9.8 has support for initial master side state compiling, but many
more components still need to be developed, it is hoped that these can be
finished for 0.9.9.

The goal is that states can be compiled on both the master and the minion
allowing for compilation to be split between master and minion.


Solaris Support
--------------------

Salt 0.9.8 sees the introduction of basic Solaris support.


Windows Support
--------------------

Salt states on windows are now much more viable thanks to contributions from
our community! States for file, user, and group management are more fully
fleshed out along with a network module. Windows users can also now manage
registry entries using the new "reg" module.