Powered by Plus3 IT Systems

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 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/<ENVIRONMENT_NAME> (e.g., a dev environment would have a corresponding ./pillar/dev directory in the Salt-content archive file).

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 <ENVIRONMENT> or --env <ENVIRONMENT> flag and argument when invoking watchmaker (per the 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.

Note

See the 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 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:

      <FORMULA_NAME>: <DOWNLOAD_URL>

  • <FORMULA_NAME> 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.

  • <DOWNLOAD_URL> 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:

      ash-linux-formula: https://github.com/<USER_ID>/<PROJECT_NAME>/archive/refs/heads/<BRANCH_NAME>.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/<USER_ID>/<PROJECT_NAME>/archive/refs/heads/<BRANCH_NAME>.zip archive-URI.

Similarly, if one is working on a new formula, specifying:

      <NEW_FORMULA_NAME>: https://github.com/<USER_ID>/<PROJECT_NAME>/archive/refs/heads/<BRANCH_NAME>.zip

Will cause the content-archive hosted at the specified GitHub URL to be unarcheved at the platform-appropriate .../formulas/<NEW_FORMULA_NAME> 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:

all:
  salt:
    [...elided...]
    user_formulas:
      <FORMULA_NAME>: <SOURCE_URL>

Note that the <FORMULA_NAME> line is indented two spaces from the user_formulas token. If improper indentation is used - for example:

all:
  salt:
    [...elided...]
    user_formulas:
    <FORMULA_NAME>: <SOURCE_URL>

Neither the .../formulas/<NEW_FORMULA_NAME> 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:<distribution> value and el_version value to identify the download url from which to pull the appropriate yum/dnf repository-definition files from

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:

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”.