Python API
Contents
API for writing service templates
TOSCA Field Specifiers
The follow are functions that are used as field specified when declaring attributes on TOSCA type. Use these if you need to specify TOSCA specific information about the field or if the TOSCA field type can’t be inferred from the Python’s attribute’s type. For example:
class MyNodeType(tosca.nodes.Root):
a_tosca_property: str = Property(name="a-tosca-property", default=None, metadata={"foo": "bar"})
Note that these functions all take keyword-only parameters (this is needed for IDE integration).
- tosca.Artifact(*, default=<dataclasses._MISSING_TYPE object>, factory=<dataclasses._MISSING_TYPE object>, name='', metadata=None)
Field specifier for declaring a TOSCA artifact.
- Parameters
default (Any, optional) – Default value. Set to None if the artifact isn’t required. Defaults to MISSING.
factory (Callable, optional) – Factory function to initialize the artifact with a unique value per template. Defaults to MISSING.
name (str, optional) – TOSCA name of the field, overrides the artifact’s name when generating YAML. Defaults to “”.
metadata (Dict[str, str], optional) – Dictionary of metadata to associate with the artifact.
- Return type
Any
- tosca.Attribute(*, default=None, factory=<dataclasses._MISSING_TYPE object>, name='', constraints=None, metadata=None, title='', status='', options=None, init=False)
Field specifier for declaring a TOSCA attribute.
- Parameters
default (Any, optional) – Default value. Set to None if the attribute isn’t required. Defaults to MISSING.
factory (Callable, optional) – Factory function to initialize the attribute with a unique value per template. Defaults to MISSING.
name (str, optional) – TOSCA name of the field, overrides the attribute’s name when generating YAML. Defaults to “”.
metadata (Dict[str, str], optional) – Dictionary of metadata to associate with the attribute.
constraints (List[DataConstraints], optional) – List of TOSCA property constraints to apply to the attribute.
status (str, optional) – TOSCA status of the attribute.
options (AttributeOptions, optional) – Typed metadata to apply.
init (Literal[False]) –
- Return type
Any
- tosca.Capability(*, default=<dataclasses._MISSING_TYPE object>, factory=<dataclasses._MISSING_TYPE object>, name='', metadata=None, valid_source_types=None)
Field specifier for declaring a TOSCA capability.
- Parameters
default (Any, optional) – Default value. Set to None if the capability isn’t required. Defaults to MISSING.
factory (Callable, optional) – Factory function to initialize the capability with a unique value per template. Defaults to MISSING.
name (str, optional) – TOSCA name of the field, overrides the capability’s name when generating YAML. Defaults to “”.
metadata (Dict[str, str], optional) – Dictionary of metadata to associate with the capability.
valid_source_types (List[str], optional) – List of TOSCA type names to set as the capability’s valid_source_types
- Return type
Any
- tosca.Property(*, default=<dataclasses._MISSING_TYPE object>, factory=<dataclasses._MISSING_TYPE object>, name='', constraints=None, metadata=None, title='', status='', options=None, attribute=False)
Field specifier for declaring a TOSCA property.
- Parameters
default (Any, optional) – Default value. Set to None if the property isn’t required. Defaults to MISSING.
factory (Callable, optional) – Factory function to initialize the property with a unique value per template. Defaults to MISSING.
name (str, optional) – TOSCA name of the field, overrides the property’s name when generating YAML. Defaults to “”.
metadata (Dict[str, str], optional) – Dictionary of metadata to associate with the property.
constraints (List[DataConstraints], optional) – List of TOSCA property constraints to apply to the property.
status (str, optional) – TOSCA status of the property.
options (PropertyOptions, optional) – Typed metadata to apply.
attribute (bool, optional) – Indicate that the property is also a TOSCA attribute. Defaults to False.
title (str) –
- Return type
Any
- tosca.Requirement(*, default=<dataclasses._MISSING_TYPE object>, factory=<dataclasses._MISSING_TYPE object>, name='', metadata=None, node_filter=None)
Field specifier for declaring a TOSCA requirement.
- Parameters
default (Any, optional) – Default value. Set to None if the requirement isn’t required. Defaults to MISSING.
factory (Callable, optional) – Factory function to initialize the requirement with a unique value per template. Defaults to MISSING.
name (str, optional) – TOSCA name of the field, overrides the requirement’s name when generating YAML. Defaults to “”.
metadata (Dict[str, str], optional) – Dictionary of metadata to associate with the requirement.
node_filter (Dict[str, Any], optional) – The TOSCA node_filter for this requirement.
- Return type
Any
- tosca.operation(name='', apply_to=(), timeout=None, operation_host=None, environment=None, dependencies=None, outputs=None, entry_state=None, invoke=None)
Function decorator that marks a function or methods as a TOSCA operation.
- Parameters
name (str, optional) – Name of the TOSCA operation. Defaults to the name of the method.
apply_to (Sequence[str], optional) – List of TOSCA operations to apply this method to. If omitted, match by the operation name.
timeout (float, optional) – Timeout for the operation (in seconds). Defaults to None.
operation_host (str, optional) – The name of host where this operation will be executed. Defaults to None.
environment (Dict[str, str], optional) – A map of environment variables to use while executing the operation. Defaults to None.
dependencies (List[Union[str, Dict[str, Any]]], optional) – List of artifacts this operation depends on. Defaults to None.
outputs (Dict[str, str], optional) – TOSCA outputs mapping. Defaults to None.
entry_state (str, optional) – Node state required to invoke this operation. Defaults to None.
invoke (str, optional) – Name of operation to delegate this operation to. Defaults to None.
- Return type
Callable
This example marks a method a implementing the
create
anddelete
operations on theStandard
TOSCA interface.@operation(apply_to=["Standard.create", "Standard.delete"]) def default(self): return self.my_artifact.execute()
API for writing configurators
- class unfurl.configurator.Configurator(*args, **kw)
Base class for implementing Configurators. Subclasses should at least implement a
run()
, for example:class MinimalConfigurator(Configurator): def run(self, task): assert self.can_run(task) return Status.ok
- Parameters
args (tosca._tosca.ToscaInputs) –
- Return type
None
- attribute_output_metadata_key: Optional[str] = None
- can_dry_run(task)
Returns whether this configurator can handle a dry-runs for the given task. (And should check
TaskView.dry_run
in during run().- Parameters
task (
TaskView
) – The task about to be run.- Returns
bool
- Return type
bool
- can_run(task)
Return whether or not the configurator can execute the given task depending on if this configurator support the requested action and parameters and given the current state of the target instance?
- Parameters
task (
TaskView
) – The task that is about to be run.- Returns
Should return True or a message describing why the task couldn’t be run.
- Return type
(bool or str)
- check_digest(task, changeset)
Examine the previous
ChangeRecord
generated by the previous time this operation was performed on the target instance and return whether it should be rerun or not.The default implementation recalculates the digest of input parameters that were accessed in the previous run.
- Parameters
task (
TaskView
) – The task that might execute this operation.changeset (
ChangeRecordRecord
) – The task that might execute this operation.
- Returns
True if configuration’s digest has changed, False if it is the same.
- Return type
bool
- exclude_from_digest: Tuple[str, ...] = ()
- classmethod get_dry_run(inputs, template)
- Parameters
template (unfurl.spec.EntitySpec) –
- Return type
bool
- get_generator(task)
- Parameters
task (unfurl.configurator.TaskView) –
- Return type
Generator
- render(task)
This method is called during the planning phase to give the configurator an opportunity to do early validation and error detection and generate any plan information or configuration files that the user may want to review before the running the deployment task.
Property access and writes will be tracked and used to establish dynamic dependencies between instances so the plan can be ordered properly. Any updates made to instances maybe reverted if it has dependencies on attributes that might be changed later in the plan, so this method should be idempotent.
- Returns
The value returned here will subsequently be available as
task.rendered
- Parameters
task (unfurl.configurator.TaskView) –
- Return type
Any
- run(task)
Subclasses of Configurator need to implement this method. It should perform the operation specified in the
ConfigurationSpec
on thetask.target
. It can be either a generator that yields one or moreJobRequest
orTaskRequest
or a regular function.- Parameters
task (
TaskView
) – The task currently running.- Yields
Optionally
run
can yield either aJobRequest
,TaskRequest
to run subtasks and finally aConfiguratorResult
when done- Returns
If
run
is not defined as a generator it must return either aStatus
, abool
or aConfiguratorResult
to indicate if the task succeeded and any changes to the target’s state.- Return type
Union[Generator, unfurl.configurator.ConfiguratorResult, unfurl.support.Status, bool]
- save_digest(task)
Generate a compact, deterministic representation of the current configuration. This is saved in the job log and used by
check_digest
in subsequent jobs to determine if the configuration changed the operation needs to be re-run.The default implementation calculates a SHA1 digest of the values of the inputs that where accessed while that task was run, with the exception of the input parameters listed in
exclude_from_digest
.- Parameters
task (
TaskView
) –- Returns
A dictionary whose keys are strings that start with “digest”
- Return type
dict
- classmethod set_config_spec_args(kw, template)
- Parameters
kw (dict) –
template (unfurl.spec.EntitySpec) –
- Return type
dict
- short_name: Optional[str] = None
shortName can be used to customize the “short name” of the configurator as an alternative to using the full name (“module.class”) when setting the implementation on an operation. (Titlecase recommended)
- should_run(task)
Does this configuration need to be run?
- Parameters
task (unfurl.configurator.TaskView) –
- Return type
Union[bool, unfurl.support.Priority]
- class unfurl.configurator.ConfiguratorResult(success, modified, status=None, configChanged=None, result=None, outputs=None, exception=None)
Represents the result of a task that ran.
See
TaskView.done()
for more documentation.- Parameters
success (bool) –
modified (Optional[bool]) –
status (Optional[unfurl.support.Status]) –
configChanged (Optional[bool]) –
result (object) –
outputs (Optional[dict]) –
exception (Optional[unfurl.util.UnfurlTaskError]) –
- Return type
None
- class unfurl.configurator.JobRequest(resources, errors=None, update=None)
Yield this to run a child job.
- Parameters
resources (List[unfurl.runtime.EntityInstance]) –
errors (Optional[Sequence[unfurl.util.UnfurlError]]) –
- get_instance_specs()
- property name
- property root
- set_error(msg)
- Parameters
msg (str) –
- property target
- class unfurl.configurator.TaskRequest(configSpec, target, reason, persist=False, required=None, startState=None)
Yield this to run a child task. (see
unfurl.configurator.TaskView.create_sub_task()
)- Parameters
configSpec (unfurl.planrequests.ConfigurationSpec) –
target (unfurl.runtime.EntityInstance) –
reason (str) –
persist (bool) –
required (Optional[bool]) –
startState (Optional[unfurl.support.NodeState]) –
- property completed: bool
bool(x) -> bool
Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.
- finish_workflow()
- Return type
None
- get_operation_artifacts()
- property name
- reassign_final_for_workflow()
- Return type
Optional[unfurl.planrequests.TaskRequest]
- class unfurl.configurator.TaskView(manifest, configSpec, target, reason=None, dependencies=None)
The interface presented to configurators.
The following public attributes are available:
- Parameters
manifest (Manifest) –
configSpec (unfurl.planrequests.ConfigurationSpec) –
target (unfurl.runtime.EntityInstance) –
reason (Optional[str]) –
dependencies (Optional[List[Operational]]) –
- Return type
None
- target
The instance this task is operating on.
- cwd
Current working directory
- Type
str
- dry_run
Dry run only
- Type
bool
- verbose
Verbosity level set for this job (-1 error, 0 normal, 1 verbose, 2 debug)
- Type
int
- add_dependency(expr, expected=None, schema=None, name=None, required=True, wantList=False, target=None)
- Parameters
expr (Union[str, collections.abc.Mapping]) –
expected (Optional[Union[unfurl.result.ResultsList, list, unfurl.result.Result]]) –
schema (Optional[collections.abc.Mapping]) –
name (Optional[str]) –
required (bool) –
wantList (bool) –
target (Optional[unfurl.runtime.EntityInstance]) –
- Return type
unfurl.configurator.Dependency
- add_message(message)
- Parameters
message (object) –
- Return type
None
- apply_work_folders(*names)
- Parameters
names (str) –
- Return type
None
- property connections: unfurl.configurator._ConnectionsMap
- create_sub_task(operation=None, resource=None, inputs=None, persist=False, required=None)
Create a subtask that will be executed if yielded by
unfurl.configurator.Configurator.run()
- Parameters
operation (str) – The operation call (like
interface.operation
)resource (
NodeInstance
) –inputs (Optional[dict]) –
persist (bool) –
required (Optional[bool]) –
- Returns
- Return type
Optional[unfurl.planrequests.TaskRequest]
- discard_work_folders()
- Return type
None
- done(success=None, modified=None, status=None, result=None, outputs=None, captureException=None)
unfurl.configurator.Configurator.run()
should call this method and return or yield its return value before terminating.>>> yield task.done(True)
- Parameters
success (bool) – indicates if this operation completed without an error.
modified (bool) – (optional) indicates whether the physical instance was modified by this operation.
status (Status) – (optional) should be set if the operation changed the operational status of the target instance. If not specified, the runtime will updated the instance status as needed, based the operation preformed and observed changes to the instance (attributes changed).
result (dict) – (optional) A dictionary that will be serialized as YAML into the changelog, can contain any useful data about these operation.
outputs (dict) – (optional) Operation outputs, as specified in the topology template.
captureException (Optional[object]) –
- Returns
- Return type
- property environ: Dict[str, str]
- fail_work_folders()
- Return type
None
- static find_connection(ctx, target, relation='tosca.relationships.ConnectsTo')
Find a relationship that this task can use to connect to the given instance. First look for relationship between the task’s target instance and the given instance. If none is found, see if there a default connection of the given type.
- Parameters
target (NodeInstance) – The instance to connect to.
relation (str, optional) – The relationship type. Defaults to
tosca.relationships.ConnectsTo
.ctx (unfurl.eval.RefContext) –
- Returns
The connection instance.
- Return type
RelationshipInstance or None
- find_instance(name)
- Parameters
name (str) –
- Return type
unfurl.runtime.NodeInstance
- get_environment(addOnly, env=None)
Return a dictionary of environment variables applicable to this task.
- Parameters
addOnly (bool) – If addOnly is False all variables in the current os environment will be included otherwise only variables added will be included.
env (Optional[dict]) –
- Returns
dict:
- Return type
dict
Variable sources (by order of preference, lowest to highest): 1. The ensemble’s environment 2. Variables set by the connections that are available to this operation. 3. Variables declared in the operation’s
environment
section.
- get_settings()
- Return type
dict
- get_work_folder(location=None)
- Parameters
location (Optional[str]) –
- Return type
unfurl.projectpaths.WorkFolder
- property inputs: unfurl.result.ResultsMap
Exposes inputs and task settings as expression variables, so they can be accessed like:
eval: $inputs::param
or in jinja2 templates:
{{ inputs.param }}
- query(query, dependency=False, name=None, required=False, wantList=False, resolveExternal=True, strict=True, vars=None, throw=False)
- Parameters
query (Union[str, dict]) –
dependency (bool) –
name (Optional[str]) –
required (bool) –
wantList (bool) –
resolveExternal (bool) –
strict (bool) –
vars (Optional[dict]) –
throw (bool) –
- Return type
Optional[Union[unfurl.result.ResultsList, unfurl.result.Result, List[unfurl.result.Result]]]
- remove_dependency(name)
- Parameters
name (str) –
- Return type
Optional[unfurl.configurator.Dependency]
- restore_envvars()
- sensitive(value)
Mark the given value as sensitive. Sensitive values will be encrypted or redacted when outputed.
- Returns
A copy of the value converted the appropriate subtype of
unfurl.logs.sensitive
value or the value itself if it can’t be converted.- Return type
- Parameters
value (object) –
- set_envvars()
Update os.environ with the task’s environ and save the current one so it can be restored by
restore_envvars
- set_work_folder(location='operation', preserve=None, always_apply=False)
- Parameters
location (str) –
preserve (Optional[bool]) –
always_apply (bool) –
- Return type
unfurl.projectpaths.WorkFolder
- update_instances(instances)
Notify Unfurl of new or changes to instances made while the configurator was running.
Operational status indicates if the instance currently exists or not. This will queue a new child job if needed.
To run the job based on the supplied spec immediately, yield the returned JobRequest.
- name: aNewInstance template: aNodeTemplate parent: HOST attributes: anAttribute: aValue readyState: local: ok state: state - name: SELF attributes: anAttribute: aNewValue
- Parameters
instances (list or str) – Either a list or string that is parsed as YAML.
- Return type
Tuple[Optional[unfurl.planrequests.JobRequest], List[unfurl.util.UnfurlTaskError]]
- property vars: dict
A dictionary of the same variables that are available to expressions when evaluating inputs.
Internal classes supporting the runtime.
- class unfurl.support.NodeState(value)
An enumeration.
- configured = 5
- configuring = 4
- created = 3
- creating = 2
- deleted = 11
- deleting = 10
- error = 12
- initial = 1
- started = 7
- starting = 6
- stopped = 9
- stopping = 8
- class unfurl.support.Priority(value)
An enumeration.
- critical = 3
- ignore = 0
- optional = 1
- required = 2
- class unfurl.support.Reason
- add = 'add'
- check = 'check'
- degraded = 'degraded'
- error = 'error'
- force = 'force'
- missing = 'missing'
- prune = 'prune'
- reconfigure = 'reconfigure'
- run = 'run'
- update = 'update'
- upgrade = 'upgrade'
- class unfurl.support.Status(value)
An enumeration.
- absent = 5
- property color
- degraded = 2
- error = 3
- ok = 1
- pending = 4
- unknown = 0
- class unfurl.result.ChangeRecord(jobId=None, startTime=None, taskId=0, previousId=None, parse=None)
A ChangeRecord represents a job or task in the change log file. It consists of a change ID and named attributes.
A change ID is an identifier with this sequence of 12 characters: - “A” serves as a format version identifier - 7 alphanumeric characters (0-9, A-Z, and a-z) encoding the date and time the job ran. - 4 hexadecimal digits encoding the task id
- Parameters
jobId (Optional[str]) –
startTime (Optional[datetime.datetime]) –
taskId (int) –
previousId (Optional[str]) –
parse (Optional[str]) –
- classmethod format_log(changeId, attributes)
format: changeidtkey=valuetkey=value
- Parameters
changeId (str) –
attributes (dict) –
- Return type
str
- log(attributes=None)
changeidtkey=valuetkey=value
- Parameters
attributes (Optional[dict]) –
- Return type
str
Runtime module
This module defines the core model and implements the runtime operations of the model.
The state of the system is represented as a collection of Instances. Each instance have a status; attributes that describe its state; and a TOSCA template which describes its capabilities, relationships and available interfaces for configuring and interacting with it.
- class unfurl.runtime.Operational
This is an abstract base class for Jobs, Resources, and Configurations all have a Status associated with them and all use the same algorithm to compute their status from their dependent resouces, tasks, and configurations
- static aggregate_status(statuses, seen)
Returns: ok, degraded, pending or None
If there are no instances, return None If any required are not operational, return pending or error If any other are not operational or degraded, return degraded Otherwise return ok. (Instances with priority set to “ignore” are ignored.)
- Parameters
statuses (Iterable[unfurl.runtime.Operational]) –
seen (Dict[int, unfurl.runtime.Operational]) –
- Return type
Optional[unfurl.support.Status]
- get_operational_dependencies()
Return an iterator of
Operational
object that this instance depends on to be operational.- Return type
Iterable[unfurl.runtime.Operational]
- has_changed(changeset)
Whether or not this object changed since the give ChangeRecord.
- Return type
bool
- class unfurl.runtime.OperationalInstance(status=None, priority=None, manualOveride=None, lastStateChange=None, lastConfigChange=None, state=None)
A concrete implementation of Operational
- Parameters
status (Optional[Union[OperationalInstance, int, str]]) –
priority (Optional[unfurl.support.Priority]) –
manualOveride (Optional[Union[OperationalInstance, int, str]]) –
lastStateChange (Optional[str]) –
lastConfigChange (Optional[str]) –
state (Optional[unfurl.support.NodeState]) –
- Return type
None
- get_operational_dependencies()
Return an iterator of
Operational
object that this instance depends on to be operational.- Return type
Iterable[unfurl.runtime.Operational]
- property local_status: Optional[unfurl.support.Status]
The local_status property.
- property manual_override_status: Optional[unfurl.support.Status]
The manualOverideStatus property.
- property priority: Optional[unfurl.support.Priority]
The priority property.
- property state: Optional[unfurl.support.NodeState]
The state property.
APIs for controlling Unfurl
Localenv module
Classes for managing the local environment.
Repositories can optionally be organized into projects that have a local configuration.
By convention, the “home” project defines a localhost instance and adds it to its context.
- class unfurl.localenv.LocalEnv(manifestPath=None, homePath=None, parent=None, project=None, can_be_empty=False, override_context=None, overrides=None, readonly=False)
This class represents the local environment that an ensemble runs in, including the local project it is part of and the home project.
- Parameters
manifestPath (Optional[str]) –
homePath (Optional[str]) –
parent (Optional[unfurl.localenv.LocalEnv]) –
project (Optional[unfurl.localenv.Project]) –
can_be_empty (bool) –
override_context (Optional[str]) –
overrides (Optional[Dict[str, Any]]) –
readonly (Optional[bool]) –
- Return type
None
- find_git_repo(repoURL, revision=None)
- Parameters
repoURL (str) –
revision (Optional[str]) –
- Return type
Optional[unfurl.repo.GitRepo]
- find_or_create_working_dir(repoURL, revision=None, basepath=None, checkout_args={})
- Parameters
repoURL (str) –
revision (Optional[str]) –
basepath (Optional[str]) –
checkout_args (dict) –
- Return type
Tuple[Optional[unfurl.repo.GitRepo], Optional[str], Optional[bool]]
- find_path_in_repos(path, importLoader=None)
If the given path is part of the working directory of a git repository return that repository and a path relative to it
- Parameters
path (str) –
importLoader (Optional[Any]) –
- Return type
Tuple[Optional[unfurl.repo.GitRepo], Optional[str], Optional[str], Optional[bool]]
- find_project(testPath, stopPath=None)
Walk parents looking for unfurl.yaml
- Parameters
testPath (str) –
stopPath (Optional[str]) –
- Return type
Optional[unfurl.localenv.Project]
- get_context(context=None)
Return a new context that merges the given context with the local context.
- Parameters
context (Optional[dict]) –
- Return type
dict
- get_external_manifest(location, skip_validation, safe_mode)
- Parameters
location (dict) –
skip_validation (bool) –
safe_mode (bool) –
- Return type
Optional[YamlManifest]
- get_local_instance(name, context)
- Parameters
name (str) –
context (dict) –
- Return type
Tuple[unfurl.runtime.NodeInstance, dict]
- get_manifest(path=None, skip_validation=False, safe_mode=None)
- Parameters
path (Optional[str]) –
skip_validation (bool) –
safe_mode (Optional[bool]) –
- Return type
YamlManifest
- get_paths()
Return a list of directories for $PATH. Includes the directory the
unfurl
script is installed in and, if asdf is installed, appends a PATH list from the.toolversions
found in the current project and the home project.- Return type
List[str]
- get_project(path, homeProject)
- Parameters
path (str) –
homeProject (Optional[unfurl.localenv.Project]) –
- Return type
- get_runtime()
- Return type
Optional[str]
- get_vault()
- get_vault_password(vaultId='default')
- Parameters
vaultId (str) –
- Return type
Optional[str]
- link_repo(base_path, name, url, revision)
- Parameters
base_path (str) –
name (str) –
url (str) –
- Return type
Tuple[str, str]
- map_value(val, env_rules)
Evaluate using project home as a base dir.
- Parameters
val (Any) –
env_rules (Optional[dict]) –
- Return type
Any
- parent: Optional[unfurl.localenv.LocalEnv] = None
- project: Optional[unfurl.localenv.Project] = None
- class unfurl.localenv.Project(path, homeProject=None, overrides=None, readonly=False)
A Unfurl project is a folder that contains at least a local configuration file (unfurl.yaml), one or more ensemble.yaml files which maybe optionally organized into one or more git repositories.
- Parameters
path (str) –
homeProject (Optional[Project]) –
overrides (Optional[dict]) –
readonly (Optional[bool]) –
- create_working_dir(gitUrl, ref=None)
- Parameters
gitUrl (str) –
ref (Optional[str]) –
- Return type
unfurl.repo.GitRepo
- find_ensemble_by_name(name)
- Parameters
name (str) –
- Return type
Optional[dict]
- find_ensemble_by_path(path)
- Parameters
path (str) –
- Return type
Optional[dict]
- find_git_repo(repoURL, revision=None)
- Parameters
repoURL (str) –
revision (Optional[str]) –
- Return type
Optional[unfurl.repo.GitRepo]
- find_git_repo_from_repository(repoSpec)
- Parameters
repoSpec (toscaparser.repositories.Repository) –
- Return type
Optional[unfurl.repo.GitRepo]
- find_or_clone(repo)
- Parameters
repo (unfurl.repo.GitRepo) –
- Return type
unfurl.repo.GitRepo
- find_or_create_working_dir(repoURL, revision=None)
- Parameters
repoURL (str) –
revision (Optional[str]) –
- Return type
Optional[unfurl.repo.GitRepo]
- static find_path(testPath, stopPath=None)
Walk parents looking for unfurl.yaml
- Parameters
testPath (str) –
stopPath (Optional[str]) –
- Return type
Optional[str]
- find_path_in_repos(path, importLoader=None)
If the given path is part of the working directory of a git repository return that repository and a path relative to it
- Parameters
path (str) –
importLoader (Optional[Any]) –
- Return type
Tuple[Optional[unfurl.repo.GitRepo], Optional[str], Optional[str], Optional[bool]]
- static get_asdf_paths(projectRoot, asdfDataDir, toolVersions={})
- Return type
List[str]
- get_context(contextName, context=None)
- Parameters
contextName (Optional[str]) –
context (Optional[dict]) –
- Return type
dict
- get_default_context()
- Return type
Any
- get_default_project_path(context_name)
- Parameters
context_name (str) –
- Return type
Optional[Any]
- get_managed_project(location, localEnv)
- Parameters
location (dict) –
localEnv (unfurl.localenv.LocalEnv) –
- Return type
Optional[unfurl.localenv.Project]
- get_manifest_path(localEnv, manifestPath, can_be_empty)
- Parameters
localEnv (unfurl.localenv.LocalEnv) –
manifestPath (Optional[str]) –
can_be_empty (bool) –
- Return type
Tuple[Optional[unfurl.localenv.Project], str, str]
- static get_name_from_dir(projectRoot)
- Parameters
projectRoot (str) –
- Return type
str
- get_relative_path(path)
- Parameters
path (str) –
- Return type
str
- get_unique_path(name)
- Parameters
name (str) –
- Return type
str
- get_vault_password(contextName=None, vaultId='default')
- Parameters
contextName (Optional[str]) –
vaultId (str) –
- Return type
Optional[str]
- get_vault_passwords(contextName=None)
- Parameters
contextName (Optional[str]) –
- Return type
Iterable[Tuple[str, Union[str, bytes]]]
- is_path_in_project(path)
- Parameters
path (str) –
- Return type
bool
- load_yaml_include(yamlConfig, templatePath, baseDir, warnWhenNotFound=False, expanded=None, action=None)
This is called while the YAML config is being loaded. Returns (url or fullpath, parsed yaml)
- Parameters
yamlConfig (unfurl.yamlloader.YamlConfig) –
templatePath (Union[str, dict]) –
- make_vault_lib(contextName=None)
- Parameters
contextName (Optional[str]) –
- Return type
Optional[ansible.parsing.vault.VaultLib]
- property name: str
- static normalize_path(path)
- Parameters
path (str) –
- Return type
str
- register_ensemble(manifestPath, *, project=None, managedBy=None, context=None)
- Parameters
manifestPath (str) –
project (Optional[unfurl.localenv.Project]) –
managedBy (Optional[unfurl.localenv.Project]) –
context (Optional[str]) –
- Return type
None
- register_project(project, for_context=None, changed=False, save_project=True)
- search_for_manifest(can_be_empty)
- Parameters
can_be_empty (bool) –
- Return type
Optional[str]
- property venv: Optional[str]
Job module
A Job is generated by comparing a list of specs with the last known state of the system. Job runs tasks, each of which has a configuration spec that is executed on the running system Each task tracks and records its modifications to the system’s state
- class unfurl.job.ConfigChange(parentJob=None, startTime=None, status=None, previousId=None, **kw)
Represents a configuration change made to the system. It has a operating status and a list of dependencies that contribute to its status. There are two kinds of dependencies:
Live resource attributes that the configuration’s inputs depend on.
Other configurations and resources it relies on to function properly.
- Parameters
parentJob (Optional[Job]) –
startTime (Optional[datetime.datetime]) –
status (Optional[Union[unfurl.runtime.OperationalInstance, int, str]]) –
previousId (Optional[str]) –
kw (Any) –
- Return type
None
- get_operational_dependencies()
Return an iterator of
Operational
object that this instance depends on to be operational.- Return type
Iterable[unfurl.runtime.Operational]
- class unfurl.job.Job(manifest, rootResource, jobOptions, previousId=None)
runs ConfigTasks and child Jobs
- Parameters
manifest (YamlManifest) –
rootResource (unfurl.runtime.TopologyInstance) –
jobOptions (unfurl.job.JobOptions) –
previousId (Optional[str]) –
- Return type
None
- can_run_task(task)
Checked at runtime right before each task is run
validate inputs
check pre-conditions to see if it can be run
check task if it can be run
- Parameters
task (unfurl.job.ConfigTask) –
- Return type
Tuple[bool, str]
- get_operational_dependencies()
Return an iterator of
Operational
object that this instance depends on to be operational.- Return type
Iterable[unfurl.job.ConfigTask]
- run_task(task, depth=0)
During each task run: * Notification of metadata changes that reflect changes made to resources * Notification of add or removing dependency on a resource or properties of a resource * Notification of creation or deletion of a resource * Requests a resource with requested metadata, if it doesn’t exist, a task is run to make it so (e.g. add a dns entry, install a package).
Returns a task.
- Parameters
task (unfurl.job.ConfigTask) –
depth (int) –
- Return type
unfurl.job.ConfigTask
- should_run_task(task)
Checked at runtime right before each task is run
- Parameters
task (unfurl.job.ConfigTask) –
- Return type
Tuple[bool, str]
- class unfurl.job.JobOptions(**kw)
Options available to select which tasks are run, e.g. read-only
does the config apply to the operation? is it out of date? is it in a ok state?
- Parameters
kw (Any) –
- Return type
None
- unfurl.job.run_job(manifestPath=None, _opts=None)
Loads the given Ensemble and creates and runs a job.
- Parameters
manifestPath (
str
, optional) – If None, it will look for an ensemble in the current working directory._opts (
dict
, optional) – the names of the command line options for creating jobs.
- Returns
The job that just ran or None if it couldn’t be created.
- Return type
(
Job
)
Init module
This module implements creating and cloning project and ensembles as well Unfurl runtimes.
- unfurl.init.clone(source, dest, ensemble_name='ensemble', **options)
Clone the
source
ensemble todest
. Ifdest
isn’t in a project, create one.source
can point to an ensemble_template, a service_template, an existing ensemble or a folder containing one of those. If it points to a project its default ensemble will be cloned.Referenced Repositories will be cloned if a git repository or copied if a regular file folder, If the folders already exist they will be copied to new folder unless the git repositories have the same HEAD. but the local repository names will remain the same.
dest
result
Inside source project
new ensemble
missing or empty folder
clone project, new or cloned ensemble
another project
new or cloned ensemble with source as spec
non-empty folder
error
- Parameters
source (str) –
dest (str) –
ensemble_name (str) –
options (Any) –
- Return type
str
Utility classes and functions
- class unfurl.logs.sensitive
Base class for marking a value as sensitive. Depending on the context, sensitive values will either be encrypted or redacted when outputed.
- exception unfurl.util.UnfurlError(message, saveStack=False, log=False)
- Parameters
message (object) –
saveStack (bool) –
log (bool) –
- Return type
None
- exception unfurl.util.UnfurlTaskError(task, message, log=40, dependency=None)
- Parameters
task (TaskView) –
message (object) –
log (int) –
- unfurl.util.filter_env(rules, env=None, addOnly=False, sub=None)
Applies the given list of rules to a dictionary of environment variables and returns a new dictionary.
- Parameters
rules (dict) – A dictionary of rules for adding, removing and filtering environment variables.
env (dict, optional) – The environment to apply the give rules to. If
env
is None it will be set toos.environ
. Defaults to None.addOnly (bool, optional) – If addOnly is False (the default) all variables in
env
will be included in the returned dict, otherwise only variables added byrules
will be includedsub (Optional[MutableMapping]) –
- Return type
Dict[str, str]
Rules applied in the order they are declared in the
rules
dictionary. The following examples show the different patterns for the rules:- foo : bar
Add
foo=bar
- +foo
Copy
foo
from the current environment- +foo : bar
Copy
foo
, or addfoo=bar
if it is not present- +!foo*
Copy all name from the current environment except those matching
foo*
- -!foo
Remove all names except for
foo
- ^foo : /bar/bin
Treat
foo
likePATH
and prepend/bar/bin:$foo
- class unfurl.util.sensitive_bytes
Transparent wrapper class to mark bytes as sensitive
- decode(*args, **kwargs)
Wrapper method to ensure type conversions maintain sensitive context
- Parameters
args (List[object]) –
kwargs (collections.abc.Mapping) –
- Return type
- class unfurl.util.sensitive_dict
Transparent wrapper class to mark a dict as sensitive
- class unfurl.util.sensitive_list(iterable=(), /)
Transparent wrapper class to mark a list as sensitive
- class unfurl.util.sensitive_str
Transparent wrapper class to mark a str as sensitive
- encode(*args, **kwargs)
Wrapper method to ensure type conversions maintain sensitive context
- Parameters
args (List[object]) –
kwargs (collections.abc.Mapping) –
- Return type
Eval module
Public Api:
map_value - returns a copy of the given value resolving any embedded queries or template strings
Ref.resolve given an expression, returns a ResultList Ref.resolve_one given an expression, return value, none or a (regular) list Ref.is_ref return true if the given diction looks like a Ref
Internal:
eval_ref() given expression (string or dictionary) return list of Result Expr.resolve() given expression string, return list of Result Results._map_value same as map_value but with lazily evaluation
- class unfurl.eval.Ref(exp, vars=None, trace=None)
A Ref objects describes a path to metadata associated with a resource.
- Parameters
exp (Union[str, collections.abc.Mapping]) –
vars (dict) –
trace (Optional[int]) –
- Return type
None
- resolve(ctx, wantList=True, strict=None)
If wantList=True (default) returns a ResultList of matches Note that values in the list can be a list or None If wantList=False return
resolve_one
semantics If wantList=’result’ return a Result- Parameters
ctx (unfurl.eval.RefContext) –
wantList (Union[bool, str]) –
strict (Optional[bool]) –
- Return type
Optional[Union[unfurl.result.ResultsList, unfurl.result.Result, List[unfurl.result.Result], Any]]
- resolve_one(ctx, strict=None)
If no match return None If more than one match return a list of matches Otherwise return the match
Note: If you want to distinguish between None values and no match or between single match that is a list and a list of matches use resolve() which always returns a (possible empty) of matches
- Parameters
ctx (unfurl.eval.RefContext) –
strict (Optional[bool]) –
- Return type
Optional[Union[unfurl.result.ResultsList, unfurl.result.Result, List[unfurl.result.Result]]]
- class unfurl.eval.RefContext(currentResource, vars=None, wantList=False, resolveExternal=False, trace=None, strict=None, task=None)
The context of the expression being evaluated.
- Parameters
currentResource (ResourceRef) –
vars (Optional[dict]) –
wantList (Optional[Union[bool, str]]) –
resolveExternal (bool) –
trace (Optional[int]) –
strict (Optional[bool]) –
task (Optional[TaskView]) –
- Return type
None
- unfurl.eval.eval_ref(val, ctx, top=False)
val is assumed to be an expression, evaluate and return a list of Result
- Parameters
val (Union[collections.abc.Mapping, str]) –
ctx (unfurl.eval.RefContext) –
top (bool) –
- Return type
List[unfurl.result.Result]
- unfurl.eval.map_value(value, resourceOrCxt, applyTemplates=True)
Resolves any expressions or template strings embedded in the given map or list.
- Parameters
value (Any) –
resourceOrCxt (Union[unfurl.eval.RefContext, unfurl.result.ResourceRef]) –
applyTemplates (bool) –
- Return type
Any