Navigation

States tutorial, part 1¶

The purpose of this tutorial is to demonstrate how quickly you can configure a
system to be managed by Salt States. For detailed information about the state
system please refer to the full states reference.

This tutorial will walk you through using Salt to configure a minion to run the
Apache HTTP server and to ensure the server is running.

Before continuing make sure you have a working Salt installation by
following the installation and the configuration instructions.

Stuck?

If you get stuck at any point, there are many ways to get help from
the Salt community including our mailing list and our
IRC channel.

Setting up the Salt State Tree¶

States are stored in text files on the master and transfered to the minions on
demand via the master’s File Server. The collection of state files make up the
State Tree.

To start using a central state system in Salt you must first set up the Salt
File Server. Edit your master config file (file_roots) and
uncomment the following lines:

Note

If you are deploying on FreeBSD via ports, the file_roots path defaults
to /usr/local/etc/salt/states.

Restart the Salt master in order to pick up this change:

Preparing the Top File¶

On the master in the directory you uncommented in the previous step
(/srv/salt by default), create a new file called
top.sls and add the following:

The top file is separated into environments (discussed later). The
default environment is base. Under the base environment a collection of
minion matches is defined; for now simply specify all hosts (*).

Targeting minions

The expressions can use any of the targeting mechanisms used by Salt —
minions can be matched by glob, pcre regular expression, or by grains. For example:

Create an sls module¶

In the same directory as your top file, create an empty file, called an
SLS module, named webserver.sls. Type the following and save the
file:

The first line, called the ID declaration, is an arbitrary identifier.
In this case it defines the name of the package to be installed. NOTE: the
package name for the Apache httpd web server may differ on your OS or distro —
for example, on Fedora it is httpd but on Debian/Ubuntu it is apache2.

The second line, called the state declaration, defines which of the
Salt States we are using. In this example, we are using the pkg state to ensure that a given package is installed.

The third line, called the function declaration, defines which function
in the pkg state module to call.

Renderers

States sls files can be written in many formats. Salt requires only
a simple data structure and is not concerned with how that data structure
is built. Templating languages and DSLs are a dime-a-dozen and everyone
has a favorite.

Building the expected data structure is the job of Salt renderers and they are dead-simple to write.

In this tutorial we will be using YAML in Jinja2 templates, which is the
default format. You can change the default by changing
renderer in the master configuration file.

Install the package¶

Next, let’s run the state we created. Open a terminal on the master and run:

Our master is instructing all targeted minions to run state.highstate. When a minion executes a highstate call it
will download the 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.

Once completed, the minion will report back with a summary of all actions taken
and all changes made.

Troubleshooting Salt

In case you don’t see the expected output, the following tips can help you
narrow down the problem.

Salt can be quite chatty when you change the logging setting to
debug:

By not starting the minion in daemon mode (-d) you can view any output from the minion as it works:

Increase the default timeout value when running salt. For
example, to change the default timeout to 60 seconds:

For best results, combine all three:

Next steps¶

This tutorial focused on getting a simple Salt States configuration working.
Part 2 will build on this example to cover more advanced
sls syntax and will explore more of the states that ship with Salt.

Project Versions

RTD Search

Full-text doc search.

Table Of Contents

How Do I Use Salt States?

States tutorial, part 2

Quick search

Enter search terms or a module, class or function name.

Navigation