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, ansible_version=2.3)¶ 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
-