Linchpin API and Context Modules
The linchpin module provides the base API for managing LinchPin, Ansible, and other useful aspects for provisioning.
- class linchpin.LinchpinAPI(ctx)
- bind_to_hook_state(callback)
Function used by LinchpinHooksclass to add callbacks
- Parameters
callback – callback function
- do_action(provision_data, action='up', run_id=None, tx_id=None)
This function takes provision_data, and executes the given action for each target within the provision_data disctionary.
- Parameters
provision_data – PinFile data as a dictionary, with
target information
- Parameters
action – Action taken (up, destroy, etc). (Default: up)
run_id – Provided run_id to duplicate/destroy (Default: None)
tx_id – Provided tx_id to duplicate/destroy (Default: None)
- do_validation(provision_data, old_schema=False)
This function takes provision_data, and attempts to validate the topologies for that data
- Parameters
provision_data – PinFile data as a dictionary, with
target information
- generate_inventory(resource_data, layout, inv_format='cfg', topology_data={}, config_data={})
- get_cfg(section=None, key=None, default=None)
Get cfgs value(s) by section and/or key, or the whole cfgs object
- Parameters
section – section from ini-style config file
key – key to get from config file, within section
default – default value to return if nothing is found.
- get_evar(key=None, default=None)
Get the current evars (extra_vars)
- Parameters
key – key to use
default – default value to return if nothing is found
(default: None)
- get_pf_data_from_rundb(targets, run_id=None, tx_id=None)
This function takes the action and provision_data, returns the pinfile data
- Parameters
targets – A list of targets for which to get the data
targets – Tuple of target(s) for which to gather data.
run_id – run_id associated with target (Default: None)
tx_id – tx_id for which to gather data (Default: None)
- get_run_data(tx_id, fields, targets=())
Returns the RunDB for data from a specified field given a tx_id. The fields consist of the major sections in the RunDB (target view only). Those fields are action, start, end, inputs, outputs, uhash, and rc.
- Parameters
tx_id – tx_id to search
fields – Tuple of fields to retrieve for each record requested.
targets – Tuple of targets to search from within the tx_ids
- property hook_state
getter function for hook_state property of the API object
- lp_journal(view='target', targets=[], fields=None, count=1, tx_ids=None)
- prepare_rundb(target, action, run_id=None, tx_id=None)
- run_hooks(state, action)
- run_target(target, resources, action, run_id=None)
- set_cfg(section, key, value)
Set a value in cfgs. Does not persist into a file, only during the current execution.
- Parameters
section – section within ini-style config file
key – key to use
value – value to set into section within config file
- set_evar(key, value)
Set a value into evars (extra_vars). Does not persist into a file, only during the current execution.
- Parameters
key – key to use
value – value to set into evars
- setup_pbar()
- setup_rundb()
Configures the run database parameters, sets them into extra_vars
- ssh(target)
- update_rundb(rundb_id, target, provision_data)
- write_results_to_rundb(results, action)
- linchpin.progress_monitor(disable_pbar, target)
- linchpin.tqdm_or_mock(disable, *args, **kwargs)
- class linchpin.context.LinchpinContext
LinchpinContext object, which will be used to manage the cli, and load the configuration file.
- get_cfg(section=None, key=None, default=None)
Get cfgs value(s) by section and/or key, or the whole cfgs object
- Parameters
section – section from ini-style config file
key – key to get from config file, within section
default – default value to return if nothing is found.
Does not apply if section is not provided.
- get_env_vars(key=None, default=None)
Get the current env_vars
- Parameters
key – key to use
default – default value to return if nothing is found
(default: None)
- get_evar(key=None, default=None)
Get the current evars (extra_vars)
- Parameters
key – key to use
default – default value to return if nothing is found
(default: None)
- load_config(workspace=None, config_path=None, search_path=None)
Update self.cfgs from the linchpin configuration file (linchpin.conf).
The following paths are used to find the config file. The search path defaults to the first-found order:
* /etc/linchpin.conf * /linchpin/library/path/linchpin.conf * <workspace>/linchpin.conf
An alternate search_path can be passed.
- Parameters
search_path – A list of paths to search a linchpin config
(default: None)
- load_global_evars()
Instantiate the evars variable, then load the variables from the ‘evars’ section in linchpin.conf. This will then be passed to invoke_linchpin, which passes them to the Ansible playbook as needed.
- log(msg, **kwargs)
Logs a message to a logfile
- Parameters
msg – message to output to log
level – keyword argument defining the log level
- log_debug(msg)
Logs a DEBUG message
- log_info(msg)
Logs an INFO message
- log_state(msg)
Logs nothing, just calls pass
Attention
state messages need to be implemented in a subclass
- set_cfg(section, key, value)
Set a value in cfgs. Does not persist into a file, only during the current execution.
- Parameters
section – section within ini-style config file
key – key to use
value – value to set into section within config file
- set_env_vars(key, value)
Set a value into env_vars. Does not persist into a file, only during the current execution.
- Parameters
key – key to use
value – value to set into evars
- set_evar(key, value)
Set a value into evars (extra_vars). Does not persist into a file, only during the current execution.
- Parameters
key – key to use
value – value to set into evars
- setup_logging()
Setup logging to the console only
Attention
Please implement this function in a subclass
- class linchpin.ansible_runner.Options(connection, module_path, forks, become, become_method, become_user, listhosts, listtasks, listtags, syntax, remote_user, private_key_file, ssh_common_args, ssh_extra_args, sftp_extra_args, scp_extra_args, start_at_task, verbosity, check, diff, vault_password_files)
- linchpin.ansible_runner.ansible_runner(playbook_path, module_path, extra_vars, vault_password_file, inventory_src='localhost', verbosity=2, console=True, env_vars=(), use_shell=False)
Uses the Ansible API code to invoke the specified linchpin playbook :param playbook: Which ansible playbook to run (default: ‘up’) :param console: Whether to display the ansible console (default: True)
- linchpin.ansible_runner.ansible_runner_24x(playbook_path, extra_vars, options, inventory_src='localhost', console=True)
- linchpin.ansible_runner.ansible_runner_28x(playbook_path, extra_vars, options, inventory_src='localhost', console=True)
- linchpin.ansible_runner.ansible_runner_shell(playbook_path, module_path, extra_vars, vault_password_file=None, inventory_src='localhost', verbosity=1, console=True, env_vars=(), check=False)
- linchpin.ansible_runner.set_environment_vars(env_vars)
Sets environment variables passed : param env_vars: list of tuples
- linchpin.ansible_runner.subprocess_runner(cmd, shell=False)
Runs subprocess commands param: cmd in a list param: shell to print stdout, stderr or not
- linchpin.ansible_runner.suppress_stdout()
This context manager provides tooling to make Ansible’s Display class not output anything when used
- class linchpin.callbacks.PlaybookCallback(display=None, options=None)
Playbook callback
- v2_runner_on_failed(result, **kwargs)
Save failed result
- v2_runner_on_ok(result)
Save ok result
- class linchpin.api.Pinfile(pinfile={}, config='linchpin.conf', workspace_path=None)
- destroy()
Destroys pinfile resources constructed through the Pinfile object
returns output dictionary
- up()
provsions pinfile resources constructed through the Pinfile object
returns output dictionary
- class linchpin.api.Workspace(path=None)
- destroy()
Destroys workspace resources constructed through the workspace object
returns output dictionary
- find_pinfile()
find_pinfile function to search pinfiles in workspace path returns pinfile path if found
- get_cfg(section, key)
get_cfg gets current linchpin.conf values based on section, key
returns string
- get_credentials_path()
get_credentials_path function gets current credentials path
returns path to credential file
- get_evar(key)
get_evar function sets extra vars in current run
- Parameters
key – string
returns value for corresponding key
- get_flag_ignore_failed_hooks()
get_flag_ignore_failed_hooks get current ignore_failed_hooks flag value
returns boolean
- get_flag_no_hooks()
get_flag_no_hooks gets current vault_encryption flag value
returns boolean
- get_inventory(inv_format='json')
get_inventory gets inventory of latest run
param: inv_format: string json/ini
returns dict/string
- get_latest_run()
get_latest_run get latest resources provisioned
returns dict
- get_vault_encryption()
get_vault_encryption gets current vault_encryption flag value
returns boolean
- get_vault_pass()
get_valut_pass get current valut_password set
returns boolean
- get_workspace()
get_workspace function gets current workspace path
- Parameters
path – path to workspace directory
returns workspace path if set
- load_data(path)
load_data function to load from workspace path
- Parameters
path – path to workspace directory
- set_cfg(section, key, value)
get_flag_ignore_failed_hooks get current ignore_failed_hooks flag value
returns boolean
- set_credentials_path(creds_path)
set_credentials_path function set credentials path
- Parameters
creds_path – path to credential directory
returns True/False
- set_evar(key, value)
set_evar function sets extra vars in current run
- Parameters
key – string
value – string
returns key,value tuple
- set_flag_ignore_failed_hooks(flag)
set_flag_ignore_failed_hooks sets current ignore_failed_hooks flag value
param: flag: boolean
- set_flag_no_hooks(flag)
set_flag_no_hooks sets no_hooks flag
param: flag: boolean
returns boolean
- set_vault_encryption(vault_enc)
set_vault_encryption sets vault_encryption flag if credentials are encrypted in vault current credentials path
param: vault_enc: boolean
returns boolean
- set_vault_pass(vault_pass)
set_vault_pass set current vault_pass value
param: vault_pass: string returns boolean
- set_workspace(path)
set_workspace function sets workspace path
- Parameters
path – path to workspace directory
returns workspace path if set
- up()
provisions workspace resources constructed through the workspace object
returns output dictionary
- validate()
validate function to validate loaded workspace/pinfile