How To Create Your First Salt Formula
This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:
- Upgrade to Ubuntu 14.04.
- Upgrade from Ubuntu 14.04 to Ubuntu 16.04
- Migrate the server data to a supported version
Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.
This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.
An Article From the Makers of SaltStack,
Submitted by: Dave Boucha
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
- Apache web server
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
- 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
Let’s start by creating a Salt Formula to make sure
Vim is installed.
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”:
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?
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
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.
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!