SLS Trees: Organizing Your Idem State Files

Idem's SLS Directories and Files: A Guide

With Idem, you'll deal with many state files (SLS). They usually come from jinja|yaml, but with rend plugins, you can write your own input renderers. In the end, they all become one python dictionary we call the SLS tree. Let's look at how to keep things organized using git-tracked repositories, include statements, and directories.

Breaking Up the Monolith

You can have all states in one big file or many smaller files in folders. Either way, Idem puts them all into one tree. One big file can be hard to manage. It's better to break it into smaller logical pieces.

Running a Single State File

Still, you can get started with idem by targeting a single file by it's relative path:

idem state databases/mysql.sls

But, the real power of Idem is unlocked when you start building a whole tree of organized files. Organizing with Folders

When you have many state files, it's good to group them in redundant directories and files for organization:

/srv/idem
│
├── databases/
│   ├── init.sls
│   ├── mysql.sls
│   ├── postgres.sls
│   └── backups/
│       ├── init.sls
│       └── logs.sls
└── users/
    ├── init.sls
    ├── admin.sls
    └── regular.sls
    └── roles/
        ├── init.sls
        └── manager.sls

Each directory can have its own init.sls to direct Idem how to run all the files within it.

Using init.sls in Directories

Let's say you have a folder with many SLS files. If there's an init.sls file in it, you can target the directory with idem, and it will start with the init.sls, which can have includes to define what other files in the directory should also be merged onto the tree. In this example, you have the states you want to run defined in /srv/idem/databases/init.sls:

idem state databases --sls-sources /srv/idem

The init.sls file tells Idem how to run all files in the folder together with include statements. We'll discuss that shortly. Combining Files with include Statements

You can use include in an SLS file to bring in other files:

include:
  - .users.roles.manager
  - .databases.backups

This helps you reuse and organize your configurations better. Since SLS files are OS independent, we use "." as a separator for nested directories. We call this the SLS file's "reference". A leading "." in the include statement tells idem to start looking for the named sls reference in the same directory as the SLS file containing the include statement. You can add more leading "."s to go up a directory up until the SLS-source root

Using Different SLS Sources

You can tell Idem where to find SLS files with the --sls-sources flag. By convention that would be in the local /srv/idem directory:

idem state admin --sls-sources /srv/idem

If you have many sources, Idem looks in the order you defined them until it finds the right source.

Conclusion

Organizing SLS files helps you manage your infrastructure with Idem better. Using git, include statements, and folders makes things clear and easy. Remember: keeping things simple and organized is key.