Difficulty: Beginner
Estimated Time: 15 minutes

The Top File

In this scenario, 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.


In this tutorial, you will learn how to:

  • Understand the structure of a Top file
  • Create a top file


To prevent you from having to set up the prerequisites to learning, we've taken the liberty of pre-installing and configuring a basic Master-Minion configuration. You will be running the commands in this tutorial in the following environment:

Hostname Operating System Salt Role Salt Version
salt-master Ubuntu 16.04.5 LTS (Xenial Xerus) Master 2019.2.0 (Fluorine)
salt-minion1 Ubuntu 16.04.5 LTS (Xenial Xerus) Minion 2019.2.0 (Fluorine)
salt-minion2 Ubuntu 16.04.5 LTS (Xenial Xerus) Minion 2019.2.0 (Fluorine)

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.

Applying and Targeting States

Step 1 of 2

Understand Top Files

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.

Understanding the 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:

Mapping out a Top File

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:

Brainstorming to 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.