API Reference

watchmaker

Watchmaker module.

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

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 will not apply any salt states. A value of 'Highstate' will apply the salt highstate. (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)

Bases: object

Prepare a system for setup and installation.

Keyword Arguments:

arguments – (Arguments) A dictionary of arguments. See watchmaker.Arguments.

install()

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

Watchmaker base manager.

class watchmaker.managers.platform_manager.PlatformManagerBase(system_params, *args, **kwargs)

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.

retrieve_file(url, filename)

Retrieve a file from a provided URL.

Supports all urllib.request handlers, as well as S3 buckets.

Parameters:

• url – (str) URL to a file.

• filename – (str) Path where the file will be saved.

create_working_dir(basedir, prefix)

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, log_pipe='all', raise_error=True)

Execute a shell command.

Parameters:

• cmd – (list) Command to execute.

• log_pipe – (str) Controls what to log from the command output. Supports three values: stdout, stderr, all. (Default: all)

• raise_error – (bool) Switch to control whether to raise if the command return code is non-zero. (Default: True)

Returns:

Dictionary containing three keys: retcode (int), stdout (bytes), and stderr (bytes).

Return type:

dict

cleanup()

Delete working directory.

extract_contents(filepath, to_directory, create_dir=False)

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.platform_manager.LinuxPlatformManager(system_params, *args, **kwargs)

Bases: PlatformManagerBase

Base class for Linux Platforms.

Serves as a foundational class to keep OS consistency.

class watchmaker.managers.platform_manager.WindowsPlatformManager(system_params, *args, **kwargs)

Bases: PlatformManagerBase

Base class for Windows Platform.

Serves as a foundational class to keep OS consistency.

watchmaker.managers.worker_manager

Watchmaker workers manager.

class watchmaker.managers.worker_manager.WorkersManagerBase(system_params, workers, *args, **kwargs)

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.

worker_cadence()

Manage worker cadence.

class watchmaker.managers.worker_manager.LinuxWorkersManager(system_params, workers, *args, **kwargs)

Bases: WorkersManagerBase

Manage the worker cadence for Linux systems.

cleanup()

Execute cleanup function.

class watchmaker.managers.worker_manager.WindowsWorkersManager(system_params, workers, *args, **kwargs)

Bases: WorkersManagerBase

Manage the worker cadence for Windows systems.

cleanup()

Execute cleanup function.

watchmaker.workers

Watchmaker workers module.

watchmaker.workers.base

Watchmaker base worker.

class watchmaker.workers.base.WorkerBase(system_params, *args, **kwargs)

Bases: object

Define the architecture of a Worker.

abstract before_install()

Add before_install method to all child classes.

abstract install()

Add install method to all child classes.

watchmaker.workers.salt

Watchmaker salt worker.

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

Bases: WorkerBase, PlatformManagerBase

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: '')

• salt_content – (str) URL to a salt content archive (zip file) that will be uncompressed in the watchmaker salt “srv” directory. This typically is used to create a top.sls file and to populate salt’s file_roots. (Default: '')

  • Linux: /srv/watchmaker/salt

  • Windows: C:\Watchmaker\Salt\srv

• salt_content_path – (str) Used in conjunction with the “salt_content” arg. Glob pattern for the location of salt content files inside the provided salt_content archive. To be used when salt content files are located within a sub-path of the archive, rather than at its top-level. Multiple paths matching the given pattern will result in error. E.g. salt_content_path='*/' (Default: '')

• salt_states – (str) Comma-separated string of salt states to execute. When “highstate” is included with additional states, “highstate” runs first, then the other states. Accepts two special keywords (case-insensitive): (Default: 'highstate')

  • none: Do not apply any salt states.

  • highstate: Apply the salt “highstate”.

• exclude_states – (str) Comma-separated string of states to exclude from execution. (Default: '')

• 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: '')

• pip_install – (list) Python packages to be installed prior to applying the high state. (Default: [])

• pip_args – (list) Options to pass to pip when installing packages. (Default: [])

• pip_index – (str) URL used for an index by pip. (Default: https://pypi.org/simple)

before_install()

Validate configuration before starting install.

install()

Install Salt.

run_salt(command, **kwargs)

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.

service_status(service)

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)

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)

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)

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)

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()

Set salt grains.

process_states(states, exclude)

Apply salt states but exclude certain states.

Parameters:

• states – (str) Comma-separated string of salt states to execute. When “highstate” is included with additional states, “highstate” runs first, then the other states. Accepts two special keywords (case-insensitive):

  • none: Do not apply any salt states.

  • highstate: Apply the salt “highstate”.

• exclude – (str) Comma-separated string of states to exclude from execution.

class watchmaker.workers.salt.SaltLinux(*args, **kwargs)

Bases: SaltBase, LinuxPlatformManager

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()

Install salt and execute salt states.

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

Bases: SaltBase, WindowsPlatformManager

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()

Install salt and execute salt states.

watchmaker.workers.yum

Watchmaker yum worker.

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

Bases: WorkerBase, LinuxPlatformManager

Install yum repos.

Parameters:

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

get_dist_info()

Validate the Linux distro and return info about the distribution.

get_mapped_dist_name()

Return a normalized dist-name value.

before_install()

Validate configuration before starting install.

install()

Install yum repos defined in config file.