Book Image

Extending SaltStack

Book Image

Extending SaltStack

Overview of this book

Salt already ships with a very powerful set of tools, but that doesn't mean that they all suit your needs perfectly. By adding your own modules and enhancing existing ones, you can bring the functionality that you need to increase your productivity. Extending SaltStack follows a tutorial-based approach to explain different types of modules, from fundamentals to complete and full-functioning modules. Starting with the Loader system that drives Salt, this book will guide you through the most common types of modules. First you will learn how to write execution modules. Then you will extend the configuration using the grain, pillar, and SDB modules. Next up will be state modules and then the renderers that can be used with them. This will be followed with returner and output modules, which increase your options to manage return data. After that, there will be modules for external file servers, clouds, beacons, and finally external authentication and wheel modules to manage the master. With this guide in hand, you will be prepared to create, troubleshoot, and manage the most common types of Salt modules and take your infrastructure to new heights!
Table of Contents (21 chapters)
Extending SaltStack
About the Author
About the Reviewer

Creating pull requests on GitHub

Whereas many project communities accept code only through mailing lists or complex websites, Salt has opted to stick with pull requests for accepting code contributions. A list of active pull requests can be found at:

The complete details of using Git are way beyond the scope of this book, but it is worth going over the steps to clone the Salt repository and put in a new pull request.

First, you will need your own fork of Salt on GitHub. If you don't have one yet, then use the Fork button at Salt's own GitHub page:

Assuming that your GitHub username is mygithubuser, your new fork will appear at:

Once you have a fork set up, you'll need to clone a copy to your computer. The following steps assume that you work in a command-line environment, such as Linux:

  1. If you have an SSH key set up, you can clone using SSH:

    $ git clone [email protected]:mygithubuser/salt.git

    Otherwise, you'll need to clone over HTTPS:

    $ git clone
  2. You will also need to add the original SaltStack repository to your local clone, to be able to create pull requests:

    $ git remote add upstream
  3. The default Git branch is develop. If you're adding a new feature to Salt, the work should be performed on a branch based on develop. To create a new branch called newfeature and switch to it, use:

    $ git checkout -b newfeature
  4. When you are ready to put in a pull request, it is best to rebase your branch to make sure it doesn't conflict with any other pull requests that have been merged since your last update:

    $ git checkout develop
    $ git fetch upstream
    $ git pull upstream develop
    $ git checkout newfeature
    $ git rebase develop


    For more information on using rebase, check out:

  5. Once you have rebased, go ahead and push your branch up to GitHub:

    $ git push origin newfeature
  6. When you visit your fork on GitHub again, you will see a link that says New Pull Request. From there, you can look at the diff readout between your branch and the current version of the develop branch on GitHub, and create your pull request when you're satisfied with it.

As with issue submission, pull requests now also have a template to use as a guide to provide useful information about describing the changes that your pull request includes.

Using other branches

If you're submitting bug fixes, then it may be more appropriate to submit them against a branch that matches a specific version of Salt. If you know which version of Salt the bug was first found in, then use that branch. The exception would be if the branch in question is so old that it is no longer being maintained. If that is the case, then choose the oldest branch that is being maintained. For instance, if the oldest maintained version is 2015.8.x, then check out the 2015.8 branch:

$ git checkout 2015.8