API Reference

watchmaker

Watchmaker module.

class watchmaker.Arguments(config_path=None, log_dir=None, no_reboot=False, log_level=None, *args, **kwargs)[source]

Bases: dict

Create an arguments object for the watchmaker.Client.

Parameters:
  • config_path – (str) Path or URL to the Watchmaker configuration file. If None, the default config.yaml file is used. (Default: None)
  • log_dir – (str) Path to a directory. If set, Watchmaker logs to a file named watchmaker.log in the specified directory. Both the directory and the file will be created if necessary. If the file already exists, Watchmaker appends to it rather than overwriting it. If this argument evaluates to False, then logging to a file is disabled. Watchmaker will always output to stdout/stderr. Additionaly, Watchmaker workers may use this directory to keep other log files. (Default: None)
  • no_reboot – (bool) Switch to control whether to reboot the system upon a successful execution of watchmaker.Client.install(). When this parameter is set, Watchmaker will suppress the reboot. Watchmaker automatically suppresses the reboot if it encounters an error. (Default: False)
  • log_level – (str) Level to log at. Case-insensitive. Valid options include, from least to most verbose:
    • critical
    • error
    • warning
    • info
    • debug

Important

For all Keyword Arguments, below, the default value of None means Watchmaker will get the value from the configuration file. Be aware that None and 'None' are two different values, with different meanings and effects.

Keyword Arguments:
 
  • admin_groups

    (str) Set a salt grain that specifies the domain _groups_ that should have root privileges on Linux or admin privileges on Windows. Value must be a colon-separated string. On Linux, use the ^ to denote spaces in the group name. (Default: None)

    admin_groups = "group1:group2"
    
    # (Linux only) The group names must be lowercased. Also, if
    # there are spaces in a group name, replace the spaces with a
    # '^'.
    admin_groups = "space^out"
    
    # (Windows only) No special capitalization nor syntax
    # requirements.
    admin_groups = "Space Out"
    
  • admin_users

    (str) Set a salt grain that specifies the domain _users_ that should have root privileges on Linux or admin privileges on Windows. Value must be a colon-separated string. (Default: None)

    admin_users = "user1:user2"
    
  • computer_name – (str) Set a salt grain that specifies the computername to apply to the system. (Default: None)
  • environment – (str) Set a salt grain that specifies the environment in which the system is being built. For example: dev, test, or prod. (Default: None)
  • salt_states – (str) Comma-separated string of salt states to apply. A value of 'None' (the string) will not apply any salt states. A value of 'Highstate' will apply the salt highstate. (Default: None)
  • s3_source – (bool) Use S3 utilities to retrieve content instead of http/s utilities. For S3 utilities to work, boto3 must be installed, and the system must have boto credentials configured that allow access to the S3 bucket. (Default: None)
  • ou_path

    (str) Set a salt grain that specifies the full DN of the OU where the computer account will be created when joining a domain. (Default: None)

    ou_path="OU=Super Cool App,DC=example,DC=com"
    
  • extra_arguments

    (list) A list of extra arguments to be merged into the worker configurations. The list must be formed as pairs of named arguments and values. Any leading hypens in the argument name are stripped. (Default: [])

    extra_arguments=['--arg1', 'value1', '--arg2', 'value2']
    
    # This list would be converted to the following dict and merged
    # into the parameters passed to the worker configurations:
    {'arg1': 'value1', 'arg2': 'value2'}
    
class watchmaker.Client(arguments)[source]

Bases: object

Prepare a system for setup and installation.

Keyword Arguments:
 arguments – (Arguments) A dictionary of arguments. See watchmaker.Arguments.
install()[source]

Execute the watchmaker workers against the system.

Upon successful execution, the system will be properly provisioned, according to the defined configuration and workers.

watchmaker.managers

Watchmaker managers module.

watchmaker.managers.base

Watchmaker base manager.

class watchmaker.managers.base.ManagerBase(system_params, *args, **kwargs)[source]

Bases: object

Base class for operating system managers.

All child classes will have access to methods unless overridden by an identically-named method in the child class.

Parameters:

system_params – (dict) Attributes, mostly file-paths, specific to the system-type (Linux or Windows). The dict keys are as follows:

prepdir:

Directory where Watchmaker will keep files on the system.

readyfile:

Path to a file that will be created upon successful completion.

logdir:

Directory to store log files.

workingdir:

Directory to store temporary files. Deleted upon successful completion.

restart:

Command to use to restart the system upon successful completion.

shutdown_path:

(Windows-only) Path to the Windows shutdown.exe command.

download_file(url, filename, sourceiss3bucket=False)[source]

Download a file from a web server or S3 bucket.

Parameters:
  • url – (str) URL to a file.
  • filename – (str) Path where the file will be saved.
  • sourceiss3bucket – (bool) Switch to indicate that the download should use boto3 to download the file from an S3 bucket. (Default: False)
create_working_dir(basedir, prefix)[source]

Create a directory in basedir with a prefix of prefix.

Parameters:
  • prefix – (str) Prefix to prepend to the working directory.
  • basedir – (str) The directory in which to create the working directory.
Returns:

Path to the working directory.

Return type:

str

call_process(cmd, stdout=False)[source]

Execute a shell command.

Parameters:
  • cmd – (list) Command to execute.
  • stdout – (bool) Switch to control whether to return stdout. (Default: False)
Returns:

None unless stdout is True. In that case, the stdout is returned as a bytes object.

Return type:

None or bytes

cleanup()[source]

Delete working directory.

extract_contents(filepath, to_directory, create_dir=False)[source]

Extract a compressed archive to the specified directory.

Parameters:
  • filepath – (str) Path to the compressed file. Supported file extensions:
    • .zip
    • .tar.gz
    • .tgz
    • .tar.bz2
    • .tbz
  • to_directory – (str) Path to the target directory
  • create_dir – (bool) Switch to control the creation of a subdirectory within to_directory named for the filename of the compressed file. (Default: False)
class watchmaker.managers.base.LinuxManager(system_params, *args, **kwargs)[source]

Bases: watchmaker.managers.base.ManagerBase

Base class for Linux Managers.

Serves as a foundational class to keep OS consitency.

class watchmaker.managers.base.WindowsManager(system_params, *args, **kwargs)[source]

Bases: watchmaker.managers.base.ManagerBase

Base class for Windows Managers.

Serves as a foundational class to keep OS consitency.

class watchmaker.managers.base.WorkersManagerBase(system_params, workers, *args, **kwargs)[source]

Bases: object

Base class for worker managers.

Parameters:
  • system_params – (dict) Attributes, mostly file-paths, specific to the system-type (Linux or Windows).
  • workers – (collections.OrderedDict) Workers to run and associated configuration data.

watchmaker.managers.workers

Watchmaker workers manager.

class watchmaker.managers.workers.LinuxWorkersManager(system_params, workers, *args, **kwargs)[source]

Bases: watchmaker.managers.base.WorkersManagerBase

Manage the worker cadence for Linux systems.

worker_cadence()[source]

Manage worker cadence.

cleanup()[source]

Execute cleanup function.

class watchmaker.managers.workers.WindowsWorkersManager(system_params, workers, *args, **kwargs)[source]

Bases: watchmaker.managers.base.WorkersManagerBase

Manage the worker cadence for Windows systems.

worker_cadence()[source]

Manage worker cadence.

cleanup()[source]

Execute cleanup function.

watchmaker.workers

Watchmaker workers module.

watchmaker.workers.salt

Watchmaker salt worker.

class watchmaker.workers.salt.SaltBase(*args, **kwargs)[source]

Bases: watchmaker.managers.base.ManagerBase

Cross-platform worker for running salt.

Parameters:
  • salt_debug_log – (list) Filesystem path to a file where the salt debug output should be saved. When unset, the salt debug log is saved to the Watchmaker log directory. (Default: '')
  • s3_source – (bool) Use S3 utilities to download salt content and user formulas from an S3 bucket. If True, you must also install boto3 and botocore. Those dependencies will not be installed by Watchmaker. (Default: False)
  • salt_content – (str) URL to a salt content archive (zip file) that will be uncompressed in the salt “srv” directory. This typically is used to create a top.sls file and to populate salt’s file_roots. (Default: '')
    • Linux: /srv/salt
    • Windows: C:\Salt\srv
  • salt_states – (str) Comma-separated string of salt states to execute. Accepts two special keywords (case-insensitive). (Default: '')
    • none: Do not apply any salt states.
    • highstate: Apply the salt “highstate”.
  • user_formulas – (dict) Map of formula names and URLs to zip archives of salt formulas. These formulas will be downloaded, extracted, and added to the salt file roots. The zip archive must contain a top-level directory that, itself, contains the actual salt formula. To “overwrite” bundled submodule formulas, make sure the formula name matches the submodule name. (Default: {})
  • admin_groups – (str) Sets a salt grain that specifies the domain groups that should have root privileges on Linux or admin privileges on Windows. Value must be a colon-separated string. E.g. "group1:group2" (Default: '')
  • admin_users – (str) Sets a salt grain that specifies the domain users that should have root privileges on Linux or admin privileges on Windows. Value must be a colon-separated string. E.g. "user1:user2" (Default: '')
  • environment – (str) Sets a salt grain that specifies the environment in which the system is being built. E.g. dev, test, prod, etc. (Default: '')
  • ou_path – (str) Sets a salt grain that specifies the full DN of the OU where the computer account will be created when joining a domain. E.g. "OU=SuperCoolApp,DC=example,DC=com" (Default: '')
run_salt(command, stdout=False)[source]

Execute salt command.

Parameters:
  • command – (str or list) Salt options and a salt module to be executed by salt-call. Watchmaker will always begin the command with the options --local, --retcode-passthrough, and --no-color, so do not specify those options in the command.
  • stdout – (bool) Switch to control whether to return stdout. (Default: False)
service_status(service)[source]

Get the service status using salt.

Parameters:service – (obj:str) Name of the service to query.
Returns:
('running', 'enabled')
First element is the service running status. Second element is the service enabled status. Each element is a bool representing whether the service is running or enabled.
Return type:tuple
service_stop(service)[source]

Stop a service status using salt.

Parameters:service – (str) Name of the service to stop.
Returns:True if the service was stopped. False if the service could not be stopped.
Return type:bool
service_start(service)[source]

Start a service status using salt.

Parameters:service – (str) Name of the service to start.
Returns:True if the service was started. False if the service could not be started.
Return type:bool
service_disable(service)[source]

Disable a service using salt.

Parameters:service – (str) Name of the service to disable.
Returns:True if the service was disabled. False if the service could not be disabled.
Return type:bool
service_enable(service)[source]

Enable a service using salt.

Parameters:service – (str) Name of the service to enable.
Returns:True if the service was enabled. False if the service could not be enabled.
Return type:bool
process_grains()[source]

Set salt grains.

process_states(states)[source]

Apply salt states.

Parameters:

states – (str) Comma-separated string of salt states to execute. Accepts two special keywords (case-insensitive):

  • none: Do not apply any salt states.
  • highstate: Apply the salt “highstate”.
class watchmaker.workers.salt.SaltLinux(*args, **kwargs)[source]

Bases: watchmaker.workers.salt.SaltBase, watchmaker.managers.base.LinuxManager

Run salt on Linux.

Parameters:
  • install_method – (str) Required. Method to use to install salt. (Default: yum)
    • yum: Install salt from an RPM using yum.
    • git: Install salt from source, using the salt bootstrap.
  • bootstrap_source – (str) URL to the salt bootstrap script. Required if install_method is git. (Default: '')
  • git_repo – (str) URL to the salt git repo. Required if install_method is git. (Default: '')
  • salt_version – (str) A git reference present in git_repo, such as a commit or a tag. If not specified, the HEAD of the default branch is used. (Default: '')
install()[source]

Install salt and execute salt states.

class watchmaker.workers.salt.SaltWindows(*args, **kwargs)[source]

Bases: watchmaker.workers.salt.SaltBase, watchmaker.managers.base.WindowsManager

Run salt on Windows.

Parameters:
  • installer_url – (str) Required. URL to the salt installer for Windows. (Default: '')
  • ash_role – (str) Sets a salt grain that specifies the role used by the ash-windows salt formula. E.g. "MemberServer", "DomainController", or "Workstation" (Default: '')
install()[source]

Install salt and execute salt states.

watchmaker.workers.yum

Watchmaker yum worker.

class watchmaker.workers.yum.Yum(*args, **kwargs)[source]

Bases: watchmaker.managers.base.LinuxManager

Install yum repos.

Parameters:repo_map – (list) List of dictionaries containing a map of yum repo files to systems. (Default: [])
get_dist_info()[source]

Validate the Linux distro and return info about the distribution.

install()[source]

Install yum repos defined in config file.