Runtime Environment

Job Variables

When a task is being evaluated the following variables are available as an expression variable or a jinja2 template variable. Instances are represented as a dictionary containing its properties and attributes and its Special keys.

inputs

A dictionary containing the inputs passed to the task’s operation.

connections

See Connections below.

SELF

The current task’s target instance.

HOST

The host of SELF.

ORCHESTRATOR

The instance Unfurl is running on (localhost)

OPERATION_HOST

Current task’s operation_host. If it is not declared, defaults to localhost.

SOURCE

If the task’s target instance is a relationship, its source instance

TARGET

If the task’s target instance is a relationship, its target instance

task

A dictionary containing the current task’s settings. Its keys include:

task Keys

name

Name of the current task

workflow

The current workflow (e.g. deploy, undeploy, or discover)

target

The name of instance the task is operating on.

operation

The name of the operation the task is running.

dryrun

(boolean) Whether the current job has the --dryrun flag set.

reason

Reason the current task was selected, e.g. “add”, “update”, “prune”, “repair”

cwd

The current working directory the task process is executing in.

verbose

An integer indicating log verbosity level: 0 (INFO) (the default), -1 CRITICAL (set by --quiet), >= 1 DEBUG (set by -v, -vv, or -vvv)

timeout

The task’s timeout value if set,

Connections

In order to execute operations on a resource Unfurl often needs connection settings, in particular credentials for authorization. These settings could be passed as inputs to each operation that needs them but this can be repetitive and inflexible. TOSCA provides Relationship Templates which describe the properties of a relationship between two nodes. Unfurl uses relationship templates as a mechanism to specify the connection settings it need to connect to resources. It does so by adding a default_for key which indicates that the relationship template doesn’t need to be explicitly referenced in the requirements section of a node template as regular relationship templates must be, but instead is applied to any target node that matches the relationship type’s specification.

Because credentials likely are specific to the user or machine running Unfurl you can define them with the localhost ensemble in .unfurl_home and by default they will be imported into the current ensemble. This can be explicitly specified when importing an external ensemble using the Connections key as described in the External ensembles section.

As described in Getting Started, the localhost ensemble provides several connection relationship templates for connecting to the the most common cloud providers.

When Unfurl executes an operation it looks for relationship templates between the OPERATION_HOST and the node that the operation is targeting, including any connection relationship templates that apply. If those templates contain any environment variables they will be set otherwise they can be accessed through to variables:

$connections

the current connections between the OPERATION_HOST and the target or the target’s HOSTs as a dictionary. The keys are the name of the relationship template or the name of the type of the relationship.

For example, these expressions all evaluate to the same value:

access_key: {{ "$connections::aws::AWS_ACCESS_KEY_ID" | eval }}

access_key: {{ "$connections::AWSAccount::AWS_ACCESS_KEY_ID" | eval }}

access_key: {{ "$connections::*::AWS_ACCESS_KEY_ID" | eval }}

In addition, because environment value because that properties

AWS_ACCESS_KEY_ID is marked as an environment variable in the relationship’s type definition, it will also be added to the environment when the operation executed.

Environment Variables

You can set the environment variables that are available while Unfurl is running in the variables section when declaring an environment. These global directives can be overridden when executing an individual operation by by adding an environment section to an operation’s implementation declaration.

In either case, the directives makes a copy of the current environment and applied each of its keys in the order they are declared, adding the given key and value as environment variables except keys starting with “+” and “-” will copy or remove the variable from the current into environment into the new one. In that case “*” and “?” are treated like filename wildcards and “!” negates the match:

name: value    # add name=value
+name:         # copy name into the enviroment
+name: default # copy value, set it to "default" if not present
+!prefix*:     # copy all except variables matching "prefix*"
-!name:        # remove all except name
-!prefix*:     # remove all except variables matching "prefix*"
^name: /bin    # treat name like a PATH and prepend value: e.g. /bin:$name

For example:

environment:
   -*:       # this will remove all environment variables
   +HOME:    # add HOME back
   FOO: bar  # set FOO = bar

The following environment variables will always be copied from the parent environment unless explicitly removed or set:

Name
TMPDIR
CURL_CA_BUNDLE
PATH
LANG
LANGUAGE
LD_LIBRARY_PATH
REQUESTS_CA_BUNDLE
SSL_CERT_FILE
HTTP_PROXY
HTTPS_PROXY
NO_PROXY
PYTHONPATH
VIRTUAL_ENV
UNFURL_TMPDIR
UNFURL_LOGGING
UNFURL_HOME
UNFURL_RUNTIME
UNFURL_NORUNTIME
UNFURL_APPROVE
UNFURL_MOCK_DEPLOY
UNFURL_LOGFILE
UNFURL_SKIP_VAULT_DECRYPT
UNFURL_SKIP_UPSTREAM_CHECK
UNFURL_SEARCH_ROOT
UNFURL_CLOUD_SERVER
UNFURL_VALIDATION_MODE
UNFURL_PACKAGE_RULES
UNFURL_LOG_FORMAT
UNFURL_RAISE_LOGGING_EXCEPTIONS
PY_COLORS
UNFURL_OVERWRITE_POLICY
UNFURL_EXPORT_LOCALNAMES
UNFURL_GLOBAL_NAMESPACE_PACKAGES

If the ASDF_DATA_DIR environment variable is set or the https://github.com/asdf-vm/asdf.git repository is part of a current project and a .tool-versions file exists (or $ASDF_DEFAULT_TOOL_VERSIONS_FILENAME) in the root of a current project, then PATH environment variable will be configured to include the paths to the tools listed in that file.