Modifying Formulae Execution-Parameters¶
The watchmaker utility bundles several SaltStack formulae. These bundled-formulae’s behaviors are, in turn, governed, by a set of Pillar-data that are also bundled with the watchmakerutility: pillar-data is how SaltStack states’ behaviors may be modified. Sites that wish to either override the bundled-formulae’s default behaviors or wish to run additional SaltStack formulae that are not in the default formula-bundle – and need to provide supporting behvior-tailoring – can do so by creating custom pillar-data.
Reference¶
When customizing Pillar content, it will also be necessary to use a site-specific, YAML-formatted configuration-file. Per the “Usage” document’s “from the CLI” section, this file is typically named config.yaml. Any file name can be used so long as it matches what is passed via the -c/--config argument to the watchmaker utility. Further, this configuration-file may be specified as hosted on the local filesystem, any HTTP/HTTPS URL or an S3-hosted URI.
The watchmaker pillar-data is delivered by way of a ZIP-formatted content-archive. While this archive-file typically takes the name salt-content.zip, any filename may be used so long as it’s properly referenced in the watchmaker configuration-file’s salt_content directive (see the config.yaml discussion for a deeper dive into this file’s contents, including a discussion of the salt_content parameter). The following exmaple configuration-file – with salt_content directive highlighted – is taken from watchmaker project:
watchmaker_version: ">= 0.27.2.dev"
all:
- salt:
admin_groups: null
admin_users: null
computer_name: null
environment: null
ou_path: null
salt_content: null
salt_states: Highstate
salt_version: '3006.1'
user_formulas:
# To add extra formulas, specify them as a map of
# <formula_name>: <archive_url>
# The <formula_name> is the name of the directory in the salt file_root
# where the formula will be placed. The <archive_url> must be a zip
# file, and the zip must contain a top-level directory that, itself,
# contains the actual salt formula. To "overwrite" submodule formulas,
# make sure <formula_name> matches submodule names. E.g.:
#ash-linux-formula: https://s3.amazonaws.com/salt-formulas/ash-linux-formula-master.zip
#scap-formula: https://s3.amazonaws.com/salt-formulas/scap-formula-master.zip
linux:
- yum:
repo_map:
#SaltEL7:
- dist:
- redhat
- centos
el_version: 7
url: https://watchmaker.cloudarmor.io/yum.defs/saltstack/salt/3006.1/salt-reposync-el7-onedir.repo
#SaltEL8:
- dist:
- almalinux
- centos
- oracle
- redhat
- rocky
el_version: 8
url: https://watchmaker.cloudarmor.io/yum.defs/saltstack/salt/3006.1/salt-reposync-el8-onedir.repo
- salt:
pip_install:
- dnspython
salt_debug_log: null
install_method: yum
bootstrap_source: null
git_repo: null
salt_version: null
windows:
- salt:
salt_debug_log: null
installer_url: https://watchmaker.cloudarmor.io/repo/saltstack/salt/windows/Salt-Minion-3006.1-Py3-AMD64-Setup.exe
status:
providers:
- key: "WatchmakerStatus"
required: False
provider_type: "aws"
- key: "WatchmakerStatus"
required: False
provider_type: "azure"
Note
If creating a new config-file for customizing your site’s watchmaker-execution, it’s recommended that config-file content not be copied from this document but from the watchmaker project, directly.
As with the configuration-file (passed via the -c/--config argument to the watchmaker utility), this file may be specified as hosted on the local filesystem, any HTTP/HTTPS URL or an S3-hosted URI.
Site-Specific Parameters¶
To implement localized-behavior with watchmaker, it will be necessary to change the salt_content paramter’s value from null to the location of a SaltStack content-bundle. As mentioned previously, the content-bundle should be delivered in the form of a ZIP-formatted content-archive.
The the overall structure and format of the archive-bundle is discussed in the Salt Contents Archive File document. Site-specific parameters – and associated values – would be handled within the archive-bundle’s Pillar data contents.
Bundle locations¶
Watchmaker currently supports pulling the Saltstack content-bundles from three types of locations: HTTP(S) server, S3 bucket or filesystem-path. The salt_content paramter’s value is stated as a URI-notation. See the following subsections for guidance on location-specification.
It’s worth noting that Watchmaker has not been tested to (directly) support accessing CIFS- or NFS-based network-shares. If it is desired to access a content-bundle from such a hosting-location, it is recommended to include share-mounting steps in any pre-Watchmaker execution-steps. Once the network-share is mounted, then watchmaker can access the content-bundle as though it was a locally-staged bundle (see below).
S3-Hosted Bundle¶
An S3-hosted bundle would be specified like:
s3://<BUCKET_NAME>/<FILE_PATH_PREFIX>/<ARCHIVE_FILE_NAME>
For example, “s3://my-site-bukkit/watchmaker/salt-content.zip”
Note
For S3-hosted URIs, it will be necessary to have ensured that the Python Boto3 modules have been installed prior to executing watchmaker
Webserver-Hosted Bundle¶
A bundle hosted on an HTTP server would be specified like:
https://<WEB_SERVER_FQDN>/<FILE_PATH_PREFIX>/<ARCHIVE_FILE_NAME>
For example, “https://wamstuff.my-site.local/watchmaker/salt-content.zip”
Note
Either HTTP or TLS-encrypted HTTP URIs are supported.
If potentially-sensitive data will be contained in the site-localization archive-file, it is recommended that access to this file be restricted. This can typically be done with authorized IP-blocks, API tokens or other “simple” authentication credentials. If this limitation comes in the form of an API token or a simple-auth credential, it will be necessary to specify the token or credentials as part of the HTTP URI.
Locally-staged Bundle¶
A locally-staged bundle (presumably downloaded and placed as part of a previously-executed launch-time automation-task) would be specified like:
file:///<FILESYSTEM_PATH_PREFIX>/<ARCHIVE_FILE_NAME>
For example, “file:///var/tmp/watchmaker/salt-content.zip”