```{eval-rst}
.. image:: ../images/cropped-plus3it-logo-cmyk.png
:width: 140px
:alt: Powered by Plus3 IT Systems
:align: right
:target: https://www.plus3it.com
```
# Dissecting The `config.yaml` File
The stock config.yaml file has five top-level directives or directive-maps:
- `watchmaker_version`
- `all`
- `linux`
- `windows`
- `status`
These directives or directive-dictionaries are used to govern the overall behavior of watchmaker's execution. See the [default config.yaml](https://raw.githubusercontent.com/plus3it/watchmaker/main/src/watchmaker/static/config.yaml) file for generic layout and exemplar-content.
## The `watchmaker_version` Directive
This directive applies a compatibility-filter to the watchmaker execution. If the installed version of watchmaker doesn't meet the version-critera set by this line, watchmaker won't work with this file's content. It's assumed that any watchmaker version that does not match the version-criteria will not (properly) support the configuration directives. Normally, the version is set as "greater than or equal to" string.
## The `all` Map
This map is used to supply default values to both saltstack and to specific SaltStack formulae. The map-keys most likely to be of interest will be:
- `valid_environments`
- `salt_content`
- `salt_states`
- `salt_version`
- `user_formulas`
### The `valid_environments` List-Parameter
This list provides a list of names of "environments" that saltstack's site-customization behavior has been configured to deliver. This will typically be used by environments that wish to customize deployments on an environment-by-environment basis (e.g. where an organization's development, testing/integration and production environments might have different endpoints to contact for things like configuring authentication) and wish to have a single `config.yaml` file to be used across all valid deployment-environments.
_Typical_ values will be `null`,`dev`, `test` and/or `prod`.
- Usage of `null` indicates no differentiation between environments – that the generic configuration should be applied. This can mean that all the environments leverage the same service-integration information or that each deployment-environment will be governed by a different `config.yaml` file.
- The others are shorthand for "development", "testing & integration" and "production", respectively.
The word "typical" was previously emphasized because _any_ value (other than `null`) is supported so long as there is a correspondingingly-named content-hierarchy in the site's custom Salt-content archive file (see the `salt-content` dictionary-key in the next section). This content-hierarchy needs to exist within the Salt-content archive file at `./pillar/` (e.g., a `dev` environment would have a corresponding `./pillar/dev` directory in the Salt-content archive file).
```{eval-rst}
.. note::
The default environment that watchmaker will apply is specified using the
``environment`` parameter. In the example, this is set to ``null`` --
meaning that a generic configuration will be applied. This value is
overridden by requesting a specific environment-configuration by using
either ``-e `` or ``--env `` flag and argument
when invoking watchmaker (per the :doc:`Usage Guide `).
```
### The `salt_content` String-Parameter
This string defines where Watchmaker should attempt to download any site-customization content from. If this value is the literal `null`, watchmaker will not attempt to download any site-customization content. Otherwise, a valid URI pointing to a customized Salt-content archive should be used. This URI can point to a locally-staged file, an HTTP/HTTPS URL or an S3 URI.
If using an S3 URI, a couple of further requirements apply:
- When installing watchmaker, it will be necessary for the `boto3` Python library to be installed
- The to-be-configured system must have read access to the specified S3 URI
By default, `watchmaker` will extract this archive-file's contents at `/srv/watchmaker/salt` (Linux) or `C:\Watchmaker\Salt\srv` (Windows) the `./` referenced elsewhere in this document will be relative to that extraction-location.
```{eval-rst}
.. note::
See the :doc:`Salt Contents Archive File ` document for a
discussion on the contents and layout of this file.
```
### The `salt_states` String-Parameter
This parameter is by Watchmaker to invoke SaltStack with the desired states selected for execution. The typical value for this parameter is `Highstate`. The `Highstate` value tells watchmaker to invoke SaltStack with the `Highstate` invoker rather than iterated-states invoker. Invoking Saltstack with the `Highstate` invoker will cause all available and activated formulas to be selected for execution.
### The `salt_version` String-Parameter
The value for this parameter instructs watchmaker which version of the Saltstack software it should download – or, if the correct version is already installed, skip re-downloading or re-installing. This will correspond to the value returned when `salt-call --version` is executed (after the `watchmaker` utility has downloaded and installed SaltStack). See the watchmaker [changelog](https://watchmaker.readthedocs.io/en/stable/changelog.html) for guidance on latest supported version of Saltstack.
### The `user_formulas` Dictionary-Parameter
This dictionary-parameter usually has no content. However, if one wishes to customize watchmaker's execution either by adding further formulae to install or to override installtion of default-formulae's contents with newer content (e.g., when testing updates to standard formulae), this dictionary should be populated. The expected value will take the form of:
```yaml
:
```
- `` will be used as the installation-location for the formula-contents into the `/srv/watchmaker/salt/formulas` (Linux) or `C:\Watchmaker\Salt\srv\formulas` (Windows) directories.
- `` will be used as the location from which to download an archive of target formula's content. This content should be in the form of a ZIP archive. Most frequently, this will be the public download-URL of a GitHub branch's (or commit-ID's) ZIP-archived, but any archive-URL that watchmaker has permission to download _should_ work
For example, if one is working on updates to the `ash-linux-formula` and has made those changes in a GitHub project, one would specify a value of:
```yaml
ash-linux-formula: https://github.com///archive/refs/heads/.zip
```
The above will cause the content normally loaded at `.../formulas/ash-linux-formula` to be replaced with the content unarchved from the `https://github.com///archive/refs/heads/.zip` archive-URI.
Similarly, if one is working on a _new_ formula, specifying:
```yaml
: https://github.com///archive/refs/heads/.zip
```
Will cause the content-archive hosted at the specified GitHub URL to be unarcheved at the platform-appropriate `.../formulas/` directory-path. It _should_ also cause an appropriate update to the SaltStack minion-configuration[^1]. If this fails to happen, there is most likely a formatting issue with your `user_formulas` declaration. The following is (a snippet of) how the declaration _should_ look:
```yaml
all:
salt:
[...elided...]
user_formulas:
:
```
Note that the `` line is indented two spaces from the `user_formulas` token. If improper indentation is used - for example:
```yaml
all:
salt:
[...elided...]
user_formulas:
:
```
Neither the `.../formulas/` directory-path will be created nor the `minion` file updated.
## The `linux` Map
This map contains two top-level keys: `yum` and `salt`. Both are also maps.
The `yum` map instructs watchmaker about where to fetch `yum`/`dnf` repository-definition files from. Using the `yum:repo_map`, watchmaker will perform a lookup using the `dist:` value and `el_version` value to identify the download `url` from which to pull the appropriate `yum`/`dnf` repository-definition files from
```{eval-rst}
.. note::
Currently, mappings for ``Red Hat 7``, ``CentOS 7``, ``Alma Linux 8``,
``CentOS 8 Stream``, ``Oracle Linux 8``, ``Red Hat 8`` and ``Rocky Linux 8``
are defined. Further Enterprise Linux distributions may be supported by
appropriate extension of this map, along with further modifcations to a few
Saltstack formulae.
```
The `salt` map is generally not modified for customization or other activities.
## The `windows` Map
Similar to the `linux` map, the `windows` map instructs watchmaker about where to fetch the Salt-minion setup-executable for Windows from.
As with the `linux` map, the `salt` dictionary is generally not modified for customization or other activities.
## The `status` Map
This map defines the "status" content that watchmaker will attempt to write as a tag to the watchmaker-managed host. Currently, only Amazon EC2s and Azure VMs are supported. Currently, this map defaults to a value of:
```yaml
status:
providers:
- key: WatchmakerStatus
required: false
provider_type: aws
- key: WatchmakerStatus
required: false
provider_type: azure
```
The watchmaker finish/status routines interpret the above to mean, "apply the tag named `WatchmakerStatus` to the managed-host and set an appropriate completion-status value[^2], but do not exit with an error if the tagging-operation fails".
[^1]: The minion-configuration file is found at `/opt/watchmaker/salt/minion` on Linux hosts and `C:\Watchmaker\Salt\conf\minion` on Windows hosts.
[^2]: The completion-status tagger will set a value of either `Completed` or `Error`.