How To Create Your First Salt Formula

<b>An Article From the Makers of <a href=“http://saltstack.com”>SaltStack</a>, Submitted by: Dave Boucha</b>

Introduction

Salt is an awesome 100% open source configuration management and remote execution tool. Salt is a new approach to infrastructure management. Easy enough to get running in minutes, scalable enough to manage tens of thousands of servers, and fast enough to communicate with them in seconds.

SaltStack is the awesome and open company behind Salt. All Salt code and features are released under the Apache 2.0 license and can be downloaded at https://github.com/saltstack/salt and your preferred OS’s package manager.

In this article we will accomplish the following:

• Create your first Salt Formula that will configure your server with the following software
  • Vim
  • Apache web server
  • PHP
  • git

This article assumes the following:

• You’ve already completed the previous tutorial Install Salt on Ubuntu 12.04
• You’re already logged in as the default root user
• We’re going to assume your server’s name is ‘minion01’. In any commmands where you see ‘minion01’ replace that with your server’s name as found in salt-key -L
• That’s it!

In the first article on installing Salt we ran a few simple commands, including a command to install Nginx. This is a great way to execute ad-hoc commands, but you don’t really want to continually configure your infrastructure this way. By creating a set of Salt Formulas you can reliably reproduce any configuration over and over. Your Salt Formulas also become great documentation of what is installed on your servers. No more wondering what’s on that old server that’s been sitting in that closet for 5 years!

Salt Formulas are simple yaml text files and by default reside on your Salt Master in /srv/salt/

Let’s start by creating a Salt Formula to make sure Vim is installed.

vi /srv/salt/vim.sls

Add the following text to your vim.sls:

vim:
  pkg:
    - installed

What’s going on here? Let me describe each line.

The first line is called the ID Declaration; essentially the “label” for this stanza. vim will be used for our package name. The name you use here must match up with the actual package name used by your package manager. “vim” for Ubuntu, “vim-core” for CentOS, for example. (In reality, the ID Declaration can be any arbitrary text and you can specify the actual package name below, but we’ll do it this way right now for simplicity’s sake)

The second line is called the State Declaration. This refers to the specific Salt State that we’re going to make use of. In this example we’re using the “pkg” state. You can find a list of all the states that Salt provides here:http://docs.saltstack.com/ref/states/all/index.html. You can even easily create your own states!

The third line is called the Function Declaration. This refers to the name of the function inside the state module that we’re going to execute. In this example it’s “installed”. Notice the tense here. Salt States are idempotent. You can execute them over and over and nothing on your server will be altered if your server already conforms to the desired state.

And that’s all! Now we can apply this state to our server like this:

salt 'minion01' state.sls vim

What if we want to make sure nano is removed from our system at the same time? Make your vim.sls look like this:

vim:
  pkg:
    - installed

nano:
  pkg:
    - removed

Are you seeing the pattern here?

In the next example we’re going to install the Apache web server and PHP at the same time. Create a file named “webserver.sls”:

vi /srv/salt/webserver.sls

Let’s add the following to “webserver.sls”

webserver_stuff:
  pkg:
    - installed
    - pkgs:
      - apache2
      - php5
      - php5-mysql

In this example, notice the “- pkgs:” argument. Each item in the list below “- pkgs:” will be passed together to your OS’s package manager to be installed together. This means only one call to “apt” or “yum” will occur. If you have a large list of packages to install this is the most efficient way to install them.

Again, you can apply this Formula to your server like this:

salt 'minion01' state.sls webserver

OK, now we’re down to our last example of installing git. Can you guess how we’re going to do it?

vi /srv/salt/git.sls

The contents:

git:
  pkg:
    - installed

And again to apply this new config do the following:

salt 'minion01' state.sls git

If we wanted to apply each of these configs at the same time we can execute the following:

salt 'minion01' state.sls vim,webserver,git

Easy, huh?

Now for the last part of this tutorial we’re going to learn the concept of a “highstate”. A “highstate” is a way for Salt to dynamically determine which Salt Formulas should be applied to a certain minion. To start with you execute a “highstate” like this:

salt 'minion01' state.highstate

This command causes the Minion to download and examine a file from the Salt Master called the “top file”. By default this file is found on the Salt Master at /srv/salt/top.sls. Let’s look at what a basic top file looks like:

base:
  '*':
    - vim
  'minion*':
    - git
    - webserver
  'minion02':
    - mongodb

In this example top.sls we have a “base” environment. For now we’re going to stick with just a default “base” environment. When the minion is told to execute a highstate, as mentioned before, the minion requests the top.sls from the master and searches for formulas that it matches. The ‘*’ is a wildcard and means that ALL minions should apply the list of formulas below it; in this case just the “vim” formula. The fourth line, ‘minion*’, also matches our minion. So that means our minion will apply the “git” and “webserver” formulas. Our minion does NOT match against ‘minion02’ so our minion will not attempt to apply the “mongodb” formula.

You’ll notice that in this example we’re only matching on the minion’s ID or name with standard globbing. You can also match on pcre, ip address and ip address range, grains and various other things. You can find a list of ways to match here.

Conclusion

We’ve created some basic Salt formulas that make use of Salt’s built in states to configure our server. This is just the very beginning of what you can do with Salt!

The Official SaltStack Walkthrough is a great way to learn more about Salt.

To learn more about all the ways Salt can help you manage your infrastructure read through the extensive documentation for Salt at http://docs.saltstack.com

Please come join the great Salt community! Our mailing list can be found here and our IRC channel is #salt on freenode.

Development of Salt takes place here: https://github.com/saltstack/salt

Please feel free to stop by and ask for help!