Manage Salt with Salt.
Table of Contents
See the full SaltStack Formulas installation and usage instructions.
If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.
If you want to use this formula, please pay attention to the FORMULA file and/or git tag,
which contains the currently released version. This formula is versioned according to Semantic Versioning.
See Formula Versioning Section for more details.
If you need (non-default) configuration, please refer to:
- how to configure the formula with map.jinja
- the
pillar.examplefile - the Special notes section
In comparison to the official Salt formula, this one provides some benefits and drawbacks:
- Configuration using mapstack instead of pillar-only
- More modular configuration for the managed domains provides more control (+readability of states)
- Managed pillar repositories to avoid the git external pillar
- Managed Salt Python environment libraries
- Should actually work on macOS
- No tests currently (!)
- No crowd knowledge/experience currently (!)
- No versatility regarding installation method (written with package installation from repo in mind)
- More control means more required knowledge
An example pillar is provided, please see pillar.example. Note that you do not need to specify everything by pillar. Often, it's much easier and less resource-heavy to use the parameters/<grain>/<value>.yaml files for non-sensitive settings. The underlying logic is explained in map.jinja.
The following states are found in this formula:
saltsalt.minionsalt.minion.configsalt.minion.packagesalt.minion.servicesalt.apisalt.api.certsalt.api.packagesalt.api.servicesalt.formulaesalt.libssalt.mastersalt.master.configsalt.master.packagesalt.master.servicesalt.pillarssalt.reposalt.sshsalt.ssh.configsalt.ssh.packagesalt.syndicsalt.syndic.packagesalt.syndic.servicesalt.cleansalt.minion.cleansalt.minion.config.cleansalt.minion.package.cleansalt.minion.service.cleansalt.api.cleansalt.api.cert.cleansalt.api.package.cleansalt.api.service.cleansalt.formulae.cleansalt.libs.cleansalt.master.cleansalt.master.config.cleansalt.master.package.cleansalt.master.service.cleansalt.pillars.cleansalt.repo.cleansalt.ssh.cleansalt.ssh.config.cleansalt.ssh.package.cleansalt.syndic.cleansalt.syndic.package.cleansalt.syndic.service.clean
Meta-state.
This includes salt.minion only.
Manages the Salt minion configuration. Depends on salt.minion.package.
Installs the Salt minion package only. Depends on salt.repo.
Starts/enables the Salt minion service at boot time. Depends on salt.minion.config.
Installs, configures and starts/enables the Salt API. Also generates a TLS certificate. Includes salt.master states.
Generates a TLS certificate + key for the Salt API. Depends on salt.api.package.
Installs Salt API only. Depends on salt.repo.
Enables and (re)starts the Salt API service. Depends on salt.api.cert and salt.master.service.
Ensures all configured formulae are present in the target destination and up to date, if configured.
This allows you to avoid the git fileserver backend,
which can become unbearably slow with growing number of files
and repositories.
You can import the list of file roots to include in your config
from salt.formulae.present. This is done by default.
Ensures the current (!) Python environment Salt runs in contains/does not contain specified modules.
Included by salt.master and salt.minion.
Installs, configures and starts/enables the Salt master.
Manages the Salt master configuration. Depends on salt.master.package.
Installs the Salt master package only. Depends on salt.repo.
Starts/enables the Salt master service at boot time. Depends on salt.master.config.
Ensures all configured pillars are present in the
target destination and up to date, if configured.
This allows you to avoid the git external pillar for
performance reasons.
You can import the list of pillar roots to include in your config
from salt.pillars.present. This is done by default.
Optionally, clears pillar cache on the master and instructs selected minions to update their in-memory pillar data on changes.
Ensures the official SaltStack repository is present.
Installs Salt SSH and manages the roster.
Manages Salt SSH roster configuration.
Installs Salt SSH only.
Installs and starts/enables Salt syndic.
Installs Salt syndic only. Depends on salt.repo.
Starts/enables Salt syndic. Depends on salt.master.service.
Meta-state.
Undoes everything performed by states of this formula. Will remove all managed Salt packages, configuration, formulae and pillars. Libs are untouched.
Stops/disables the Salt minion service, removes minion configuration and the Salt minion package.
Stops/disables the Salt API service, removes TLS certificate/key and the Salt API package.
Removes all cloned formula repositories.
Stops/disables the Salt master service, removes master configuration and the Salt master package.
Removes all cloned pillar repositories.
Ensures the Salt repository is not configured.
Removes Salt SSH and the roster.
Removes the roster.
Removes Salt SSH. Depends on salt.ssh.config.clean.
Disables/stops and removes Salt syndic.
Removes Salt syndic. Depends on salt.syndic.service.clean.
Stops/disables Salt syndic.
Commit message formatting is significant!
Please see How to contribute for more details.
pre-commit is configured for this formula, which you may optionally use to ease the steps involved in submitting your changes.
First install the pre-commit package manager using the appropriate method, then run bin/install-hooks and
now pre-commit will run automatically on each git commit.
$ bin/install-hooks pre-commit installed at .git/hooks/pre-commit pre-commit installed at .git/hooks/commit-msg
There is a script that semi-autodocuments available states: bin/slsdoc.
If a .sls file begins with a Jinja comment, it will dump that into the docs. It can be configured differently depending on the formula. See the script source code for details currently.
This means if you feel a state should be documented, make sure to write a comment explaining it.