# Notes for salt files, like tutorial
*(Some of files have sensitive data removed, and some files, particularly in pillar folder, are removed as they bring no new info to this tutorial.)*

## 0. Reminder about top.sls files
Used in pillar and states folders, these file map minion id to a list(s) of states and pillars.
Mapping uses `*` wildcard, allowing to have several lists that apply to a particular id.
This is useful in reusing overall functional configurations.

## 1. Process of adding some configuration

### 1.0. Assumptions and useful tools reminder
Assume that minion is already approved and accessible with `<id>`.

Check what it is with `salt <id> grains.items`. Note that this is an execution of function `items` from execution module `grains` [salt.modules.grains](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.grains.html).

Check what pillar are set for minion with `salt <id> pillar.items` that uses function `items` from execution module `pillar` [salt.modules.pillar](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.pillar.html).

### 1.1. Add simple state file
Take for example `salt/apt.sls` file that defines `apt` state. In `salt/top.sls` we add `apt` to all, identified with `'*'`.

`apt` states file has two sections. Each is a state. Each uses function `managed` from states module `file` [salt.states.file](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html). Each file in `apt` is small, so we put its content directly in state's statement as `contents` argument (ya, looking at docs is useful).

### 1.2. Reacting to config changes (e.g. service restarts)
Very often we want to react on change of configuration file.
Take for example `salt/salt-minion.
After state(s) for config file(s) we add a state section with `cmd.run` that is set to run `onchanges` of specified file(s). See [run in salt.states.cmd](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.cmd.html#salt.states.cmd.run).

### 1.3. Bigger config files
Take an example of `salt/bind9`.
It uses `file.managed` with content sourced from file location that starts with `salt://`, with root being `salt/` folder (side note: any minion can see everything in `salt/` folder).
`file.recurse` is used to keep file tree in sync.

Another sample state `net` is defined with file `salt/net/init.sls`. Use of folder allows to keep relevant files together.

Note that `salt/net/init.sls` itself uses Jinja templating, and uses `template` arguments in some `file.managed` sections.
This allows use of templating with *any* configuration.

### 1.4. Specific minion info, pillars
Once we have states articulated, we may extract some minion-specific data into pillar(s) for that particular minion.
For example, state `haproxy` (file `salt/haproxy.sls`) uses `contents_pillar` argument in `file.managed`.
Pillar file `pillar/s-1-1/haproxy.sls` defines `haproxy` as a string with content.

Separation of specific data makes states reusable.
On another hand, we can hide in pillars configuration data that shouldn't be seen by everyone, like firewall rules. Note `ufw` parts in `net` state and pillars `net`, `salt/net`, `s-1-1/net`, `s-0-111/net`.

### 1.5. Examples of other functionality from modules
Many states use `pkg.installed` from [state module](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html#salt.states.pkg.installed) to install stuff.

State file `salt/zfs.sls` uses `zfs.filesystem_present` from [state module](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.zfs.html#salt.states.zfs.filesystem_present) to ensure presence of zfs volumes.
Pillar information is used to say which volumes are needed, using loop in a template.

In command line one may do anything with minions using `salt <id> cmd.run "some command with args"`, that uses [execution module](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.cmdmod.html#salt.modules.cmdmod.run). Note that `cmdmod` is shortened to `cmd`.

## 2. List of settings
Files have a few reusable simple settings:
- apt
- bind9
- salt
- lxc (simple addition of container making tools)
- docker
- docker-registry
- net (with netplan and ufw firewalling)
- certbot (to run nearby either nginx, or haproxy)
- haproxy (similar can be written for nginx)

Use these as examples, or directly (but read it, to know what your machines swallow).