SaltStack Fundamentals

Get Started Tutorial

Apply and Target States

You'll learn how to:

  • Create a Top file to match systems with Salt state files

Estimated time: 15 minutes 


Let’s review what we’ve learned so far:

  • How to run a single command from the command line on one or more Salt minions.
  • Group multiple commands and use new commands to define re-usable states.

Notice how the Salt state we created in the previous section did not contain any information about the Salt minions that should receive the configuration? Salt states are generic by design, and describe only how a configuration should be achieved.

In this section we’ll learn about a different file, called the Top file, that describes where states should be applied.

States and the Top file work together to create the core of SaltStack’s configuration management capability.

Introducing the Top File

The Top file is used to apply multiple state files to your Salt minions during a highstate. The states that are applied to each system are determined by the targets that are specified in the Top file.

Create your own Top file

Before we create a Top file, it might be useful to take a moment to think about what what your system configurations look like. Consider the different types of systems you set up, and what is common and unique about each. Each system can receive multiple configurations, so start with the most general configurations and work your way down to the specifics.

For example, you might start with a simple description similar to the following:

In the SaltStack paradigm, the list itself would be the Top file, and each item on the list would be a state. Targets are used within the Top file to define which states are applied to each Salt minion.

The following example shows how our configurations might be translated to YAML and represented in a Top file:

When the Top file is evaluated, Salt minions execute all states that are defined for any target that they match. For example, a system with a Salt minion ID of atl-web4-prod would apply the vim, scripts, users, apache, python, and django states.

Now that we understand the purpose of the Top file, lets go ahead and create one. If you are using the Vagrant demo files you’ll notice that there is already a top.sls file in the saltstack/salt directory, so we’ll just update that one. Otherwise you can create a new file. Add the following to your top.sls file:

    - common
    - nettools

Hopefully it is clear to you what will happen when this is applied, so let’s try it. On your Salt master, run the following command to apply the Top file:

salt '*' state.apply
#calling state.apply with no arguments starts a highstate.

As you expected, minion1 and minion2 both applied the common state, and minion1 also applied the nettools state.

Using what you know about the targeting system, you now know how to create state and run them on the correct Salt minions using the Top file.

What’s Next?

You should now have a basic understanding of the SaltStack remote execution capabilities, how to create simple states, and how to apply these states to managed systems.

If you are ready to keep going, continue to the Configuration Management Get Started Guide.