API¶
Core modules¶
- class opslib.components.Component(**kwargs)¶
The basic building block to define the stack. See Components.
- add_commands(cli)¶
Called when the CLI is constructed. Override this method to add custom commands.
- Parameters:
cli – A
ComponentGroup
that represents the CLI of this component.
- build()¶
Called when the component is attached to a parent. Override this method to add sub-components.
- opslib.components.walk(component)¶
Iterate depth-first over all child components. The first item is
component
itself.
- class opslib.props.Prop(type, default=<object object>, lazy=False)¶
The Prop class is the definition of a component Prop. See Props.
- class opslib.props.InstanceProps(instance, kwargs)¶
The InstanceProps class is a container for instance props (see Props). Typically it’s found as the
.props
attribute of aComponent
instance. The props themselves are attributes of this object.
- class opslib.lazy.Lazy(func, *args, **kwargs)¶
A Lazy object wraps a value that will be available at a later time.
When evaluated, it invokes its arguments as
func(*args, **kwargs)
, caches the result and returns it.
- class opslib.lazy.NotAvailable¶
Bases:
KeyError
The NotAvailable exception indicates that the requested
Lazy
value depends on some data that is not available at this time.
- opslib.lazy.evaluate(ob)¶
Evaluate
Lazy
objects and return the result. If invoked with a non-Lazy argument, it traverses nested lists and dictionaries, making copies of them, and evaluating any Lazy values inside.
- opslib.lazy.lazy_property(func)¶
Similar to
@property
, makes a method function like an instance property. When the property is retrieved, it returns aLazy
object, that invokes the method when evaluated.
- class opslib.operations.Operation(**kwargs)¶
The Operation class represents an operation to be performed on a selection of
Component
objects.- Parameters:
dry_run – If
True
, the operation will not have effects on the target, just show what would change.deploy – If
True
, apply changes to the target. May be combined withdry_run
.refresh – If
True
, inspect the state of the target and save it in local state.destroy – If
True
, destroy the target resource.
- opslib.operations.apply(component, **kwargs)¶
Apply the specified operation on
component
. It will also be applied recursively, depth-first, to all child components.The order differs depending on the operation. For
refresh
anddeploy
, children are processed first. Fordestroy
, the parent component is processed first, then its children.- Parameters:
component – The
Component
on which to apply the operation.kwargs – Keyword arguments are forwarded to
Operation
.
- class opslib.results.Result(changed=False, output='', failed=False)¶
The Results class wraps the outcome and output of an operation.
- Variables:
changed –
True
if the operation changed anything.output – Textual output.
failed –
True
if the operation ended in failure.
- raise_if_failed(*args)¶
Check if the
failed
flag is set, and if so, raisesOperationError
.- Parameters:
args – Arguments to be passed to OperationError.
- class opslib.results.OperationError(*args, result)¶
Exception raised when an operation fails.
- Variables:
result – The operation’s
Result
, useful to figure out what went wrong.
- class opslib.local.LocalRunResult(completed, encoding=None)¶
Bases:
Result
The result of a call to
run()
. In addition to the fields inherited fromResult
, it contains the following:
- opslib.local.run(*args, input=None, capture_output=True, encoding='utf8', extra_env=None, exit=False, check=True, exec=False, **kwargs)¶
The
run
function is a thin wrapper aroundsubprocess.run()
. It captures output and exit code and returns them as aLocalRunResult
object.- Parameters:
input – Content to send to stdin (optional).
capture_output – Capture stdout and stderr. Enabled by default.
encoding – Text encoding for stdin, stdout and stderr. Defaults to
"utf8"
. Set toNone
to disable encoding and use rawbytes
.extra_env – A dictionary of environment variables to send to the subprocess, in addition to the ones in
os.environ
.exit – If set, when the subprocess is complete, call
sys.exit()
with the subprocess exit code. Useful when wrapping commands for the CLI.check – If True (default), when the subprocess exits with an error code, raise
OperationError
.exec – Instead of calling
subprocess.run()
, invoke the command usingos.execvpe()
. This will replace the current program with the new one. Useful when wrapping commands for the CLI.
- opslib.cli.get_main_cli(get_stack)¶
Create a
click.Group
for the given stack.- Parameters:
get_stack – Callable that returns a
Stack
.
- opslib.cli.main()¶
Main entry point for the
opslib
CLI command. It tries to runimport stack
and expects to find a stack namedstack.stack
, which it sends toget_main_cli()
.The
OPSLIB_STACK
environment variable can be set to import something other thanstack
.
- class opslib.cli.ComponentGroup(name=None, commands=None, **attrs)¶
Bases:
Group
- forward_command(*args, **kwargs)¶
A specialized
click.Group.command()
for commands that invoke another command. Any unprocessed arguments are sent as anargs
tuple, to be forwarded to the other command. It’s equivalent to the following:@cli.command( context_settings=dict( ignore_unknown_options=True, allow_interspersed_args=False, ) ) @click.argument("args", nargs=-1, type=click.UNPROCESSED) def foo(args): print("foo called with:", args)
Batteries¶
- class opslib.places.BaseHost(**kwargs)¶
Abstract component for a host.
- add_commands(cli)¶
Called when the CLI is constructed. Override this method to add custom commands.
- Parameters:
cli – A
ComponentGroup
that represents the CLI of this component.
- ansible_action(**props)¶
Shorthand function that returns an
AnsibleAction
component withhostname
andansible_variables
set from this host. Keyword arguments are forwarded as props to AnsibleAction.
- command(**props)¶
Shorthand function that returns a
Command
component withhost
set to this host. Keyword arguments are forwarded as props to the Command.
- directory(path, **props)¶
Shorthand function that returns a
Directory
component withhost
set to this host. Keyword arguments are forwarded as props to the Directory.
- file(**props)¶
Shorthand function that returns a
File
component withhost
set to this host. Keyword arguments are forwarded as props to the File.
- sudo()¶
Returns a copy of this host that has the
with_sudo
flag set. This means that commands will be run usingsudo
, and Ansible will be invoked withbecome=True
.
- class opslib.places.LocalHost(**kwargs)¶
Bases:
BaseHost
The local host on which opslib is running. It receives no props.
- Variables:
hostname – Set to
localhost
.ansible_variables – Two variables are set:
ansible_connection
islocal
;ansible_python_interpreter
is set tosys.executable
.
- class opslib.places.SshHost(**kwargs)¶
Bases:
BaseHost
Connect to a remote host over SSH. Most props configure how the
ssh
subcommand is invoked. If you have already configured the host in~/.ssh/config
, it’s enough to specifyhostname
, as you would in the terminal.- Parameters:
hostname – Name of the remote host.
username – Username to log in.
port – Port number.
private_key_file – Path to an SSH identity file to be used for authentication.
config_file – SSH configuration file to use instead of
~/.ssh/config
.interpreter – Python interpreter to be used by Ansible. Set as the
ansible_python_interpreter
variable. Defaults to"python3"
.
- class opslib.places.Directory(**kwargs)¶
The Directory component creates a directory on the host.
- Parameters:
host – The parent host.
path – Absolute path of the directory.
mode – Unix file permissions (optional).
owner – The name of the user owning the directory (optional).
group – The name of the group owning the directory (optional).
- command(**props)¶
Shorthand function that returns a
Command
component withcwd
set to this directory andhost
set to this host. Keyword arguments are forwarded as props to the Command.
- file(name, **kwargs)¶
Shorthand function that returns a
File
with the same host, and the path being a child path ofself.path
.
- class opslib.places.File(**kwargs)¶
The File component creates a regular file on the host.
- Parameters:
- class opslib.places.Command(**kwargs)¶
The Command component represents a command that should be run on the host during deployment.
- Parameters:
host – The parent host.
cwd – Optional
Path
where command should run.args – Command arguments array. The first argument is the command itself. Defaults to
[]
, which invokes the shell, useful with theinput
parameter.input – Content to be sent to standard input. Defaults to no input.
run_after – A list of components that trigger this command to be run. If empty, the command will always be run, otherwise it will run once, and then only run after one of the components changes.
- run(**kwargs)¶
Run the command defined by this component.
- Parameters:
kwargs – Extra keyword arguments to be forwarded to the
run
method of the host.
- class opslib.ansible.AnsibleAction(**kwargs)¶
The AnsibleAction component executes an Ansible module.
- Parameters:
host –
BaseHost
to act on.module – Name of the Ansible module to invoke, e.g.
"ansible.builtin.copy"
.args – Dictionary of arguments for the module. Consult each module’s documentation for the args (or Parameters) it supports.
format_output – Optional callback used to format the result output. If provided, it will be called with a single parameter, the
AnsibleResult
object; its return value will be used to overwrite theoutput
attribute of the result.
- run(check=False)¶
Call
run_ansible()
with the action defined by this component.
- class opslib.ansible.AnsibleResult(data, failed)¶
The result of an
AnsibleAction
, or a call torun_ansible()
. In addition to the fields inherited fromResult
, it contains the following:- Variables:
data – The original result object reported by Ansible. The format varies quite a bit from module to module.
exception – If the action failed, this contains the stack trace from Ansible, as
str
.msg – If the action failed, this contains the error message from Ansible.
stdout – The
stdout
field fromdata
.stderr – The
stderr
field fromdata
.
- opslib.ansible.run_ansible(hostname, ansible_variables, action, check=False)¶
Invoke Ansible with a single action. This creates and executes an Ansible Play, with a single host, and a single task that contains the given action. Returns an
AnsibleResult
object.Instead of directly calling this function, typically one would create an
AnsibleAction
in the stack, but it’s usable directly if need be. It encapsulates all setup and teardown of the Ansible machinery and exposes only the essential arguments.- Parameters:
hostname – Name of the host to act on.
ansible_variables – List of variables to configure Ansible.
action – The Ansible action. It should be a dictionary with members module and args.
check – If
True
, run Ansible in “check” mode, which will not apply any changes, just show differences.
- class opslib.terraform.TerraformProvider(**kwargs)¶
The TerraformProvider component represents a Provider in the Terraform universe. After a provider is defined,
TerraformResource
components can be created from it.- Parameters:
name – The name of the provider, e.g.
"aws"
.source – Provider source, e.g.
"hashicorp/aws"
.version – Version requirement, e.g.
"~> 4.0"
(optional but highly recommended).config – Provider configuration (optional). Most providers require some level of configuration, although it can sometimes be set through environment variables; consult each provider’s documentation for details.
- data(**props)¶
Shorthand method to create a
TerraformDataSource
, withprovider
set to this component.
- resource(**props)¶
Shorthand method to create a
TerraformResource
, withprovider
set to this component.
- class opslib.terraform.TerraformResource(**kwargs)¶
The TerraformResource component creates a single Resource through Terraform.
- Parameters:
provider – The
TerraformProvider
for this resource. Technically optional because some builtin resource types of Terraform don’t belong to any provider.type – Type of resource, e.g.
"aws_vpc"
.args – Arguments of the resource (
dict
). Consult the provider’s documentation for the arguments supported by each resource. May beLazy
.output – List of attributes exported by the resource to be fetched from Terraform. They are available on the
output
property. (optional)
- import_resource(resource_id)¶
Import an existing resource into Terraform.
- property output¶
Output values returned from Terraform.
- run(*args, terraform_init=True, **kwargs)¶
Run the
terraform
command with the given arguments.
- class opslib.terraform.TerraformDataSource(**kwargs)¶
The TerraformDataSource component retrieves data through a Terraform data source.
- Parameters:
provider – The
TerraformProvider
for this data source. Technically optional because some builtin data source types of Terraform don’t belong to any provider.type – Type of data source, e.g.
"aws_vpc"
.args – Arguments of the data source (
dict
). Consult the provider’s documentation for the arguments supported by each data source. May beLazy
.output – List of attributes exported by the data source to be fetched from Terraform. They are available on the
output
property. (optional)
- property output¶
Output values returned from Terraform.
- run(*args, terraform_init=True, **kwargs)¶
Run the
terraform
command with the given arguments.
- class opslib.terraform.TerraformResult(tf_result)¶
The result of an invocation of
terraform
. In addition to the fields inherited fromResult
, it contains the following:- Variables:
tf_result – The original
LocalRunResult
of invoking theterraform
command.