salt-formula-manager/README.md

# Salt Formula Manager

Tool to automate the downloading of Salt formulas

### Table of Contents

1. [Overview - what you just read...](#overview)
2. [Usage - How to use this thing](#usage)
3. [Configuration - Getting this thing ready to roll](#configuration)
4. [To Do - What needs getting done](#to-do)
5. [License - Licensing information](#license)
6. [Contact - How to contact me](#contact)

## Overview

The goal of this tool is provide a flexible, yet powerful tool to manage Salt formulas. It aims to support many different configurations in an intuitive manner, such as, but not limited to:

* Downloading formulas from multiple sources
* Keeping formula management to one single configuration file
* Avoiding needing to modify the Salt master config file to add new formula sources

Indeed, SaltStack are working on a tool, Salt Package Manager, that aims to do similar things. However, that tool feels a little "hacky", in my opinion, and doesn't use some of the tools that are already available to us, such as git/GitHub, and it requires the use of hosting packages out of a separate repository. Granted, that approach does have its positives, but I felt that I needed something a little lighter than that solution. To each their own :)

## Usage

As it currently stands, you should only need to run a simple `salt-formula-manager.py` in a directory containing your SFM configuration. There are plans to 1) add a "system-wide" or "default" configuration path, so you do not need to be in a specific directory to run this, and 2) to add a `-c /path/to/config.yaml` parameter to override the default path to the configuration file.

## Configuration

Here's an explanation of the current list of configuration parameters...

#### `formulas_url`

Defines the default remote URL to use for Salt formulas. The default here is a common repository (https://github.com/SaltStack-Formulas) that, theoretically, most of your formulas will share.

#### `formulas_dir`

This defines where your formulas are going to be stored. This can be the same directory as your locally-written Salt states, or this can be an entirely separate directory altogether (Note: you WILL need to have permission to write to this directory).

#### `purge_formulas`

If true, SFM will attempt to remove all of the "unmanaged" Salt formulas that are present in the directory defined by `formulas_dir` (noted above).

#### `formulas`

This is just a simple hash/list of formulas to download/manage. Simply giving an array entry (e.g. `- munin` - note there is no colon), or an empty hash (e.g. `- munin: {}`) will let SFM attempt to guess the URL and destination directory. 

#### Formula definitions

Each formula listed (as noted above) has specific options that may be set to change the default.

#### `url`

The remote URL to use - theoretically, this should work with SSH URLs if you have permission to clone over SSH, otherwise, HTTPS URLs will work just fine if you have permission to access the repository.

#### `git_branch`

This defines a specific Git branch to track for changes, if the formula is not on said branch, SFM will attempt to checkout the desired branch.

#### `name`

This option is not very important - if the URL isn't specified for a formula, then SFM will attempt to guess the formula's repository URL based off of the default repository URL and the name/title of the formula. If the name isn't specified, SFM will use the title of the title of the entry appended with "-formula" as its name. Thus, a name of "munin-form" with the default URL "https://github.com/SaltStack-Formulas" when end up with "https://github.com/SaltStack-Formula/munin-form"

**Note:** I'm debating removing this in a future release, as I don't see the use beyond saving a few characters here and there.

## To Do

What still needs done...

* Creating symlinks from formulas directory to states directory (to avoid having to check/modify the Salt master configuration)
* Check/modify the Salt master's configuration to allow loading of the downloaded formulas
* Logging actions, failures, etc into a log file
* Find some way of properly tracking versions in a logical and flexible mannger
* Tracking a specific commit (maybe?)
* Tracking a tag (maybe?)
* Better configuration management (e.g. maybe using a class to handle configuration, where to put the configuration files, etc)
* Maybe not running a `git pull` on every repo, every time the script is run?
* Managing multiple Salt environments

## License

This program is licensed under the Mozilla Public License, version 2.0 (I'm not a license guru, if this needs to be changed to comply with other licenses, I'll gladly change it)

## Contact

Email me at: brotherballantine@gmail.com

Or you can find me on:
* [Mastodon](https://mastodon.rocks/@brotherballan)
* Wire (@brotherballan)
* [Google+](https://plus.google.com/+GregoryBallantine1)