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