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 </ref/states/index>
.
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.
States are stored in text files on the master and transferred 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, the Salt File Server must first be set up. Edit the master config file (:conf_master:file_roots) and uncomment the following lines:
file_roots:
base:
- /srv/salt
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:
pkill salt-master
salt-master -d
On the master, in the directory uncommented in the previous step, (/srv/salt
by default), create a new file called :conf_master:top.sls <state_top> and add the following:
base:
'*':
- webserver
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 (*
).
The expressions can use any of the targeting mechanisms used by Salt — minions can be matched by glob, PCRE regular expression, or by
grains </topics/targeting/grains>
. For example:base: 'os:Fedora': - match: grain - webserver
In the same directory as the top file
, create an empty file named webserver.sls
, containing the following:
apache: # ID declaration
pkg: # state declaration
- installed # function declaration
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 depending on 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
<salt.states.pkg>
to ensure that a given package is installed.
The third line, called the function declaration
, defines which function in the pkg state <salt.states.pkg>
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
</ref/renderers/index>
and they are dead-simple to write.
In this tutorial we will be using YAML in Jinja2 templates, which is the default format. The default can be changed by editing :conf_master:renderer in the master configuration file.
Next, let's run the state we created. Open a terminal on the master and run:
% salt '*' state.highstate
Our master is instructing all targeted minions to run state.highstate
<salt.modules.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.
Note that in the
example <targeting-minions>
above, the SLS filewebserver.sls
was referred to simply aswebserver
. The namespace for SLS files follows a few simple rules:
- The
.sls
is discarded (i.e.webserver.sls
becomeswebserver
).
- Subdirectories can be used for better organization.
- Each subdirectory is represented by a dot.
webserver/dev.sls
is referred to aswebserver.dev
.- A file called
init.sls
in a subdirectory is referred to by the path of the directory. So,webserver/init.sls
is referred to aswebserver
.- If both
webserver.sls
andwebserver/init.sls
happen to exist,webserver/init.sls
will be ignored andwebserver.sls
will be the file referred to aswebserver
.
Troubleshooting Salt
If the expected output isn't seen, the following tips can help to narrow down the problem.
- Turn up logging
Salt can be quite chatty when you change the logging setting to
debug
:salt-minion -l debug
- Run the minion in the foreground
By not starting the minion in daemon mode (
-d <salt-minion -d>
) one can view any output from the minion as it works:salt-minion &
Increase the default timeout value when running salt
. For example, to change the default timeout to 60 seconds:
salt -t 60
For best results, combine all three:
salt-minion -l debug & # On the minion
salt '*' state.highstate -t 60 # On the master
This tutorial focused on getting a simple Salt States configuration working. Part 2 <states_pt2>
will build on this example to cover more advanced sls
syntax and will explore more of the states that ship with Salt.