Uploading Files

Blueprints often require that parameterized scripts and configuration files are available to be copied to the target VM. These must be URLs resolvable from the Brooklyn instance, or on the Brooklyn classpath.

There are two types of file that can be uploaded: plain files and templated files. A plain file is uploaded unmodified. A templated file is interpreted as a FreeMarker template. This supports a powerful set of substitutions. In brief, anything (unescaped) of the form ${name} will be substituted, in this case looking up "name" for the value to use.

Writing templates

Templated files (be they configuration files or scripts) give a powerful way to inject dependent configuration when installing an entity (e.g. for customising the install, or for referencing the connection details of another entity). Available substitutions are:

Additional substitutions can be given per-entity by setting the template.substitutions key. For example, to include the address of an entity called db:

brooklyn.config
  template.substitutions:
    databaseAddress: $brooklyn:entity("db").attributeWhenReady("host.address")

The value can be referenced in a template with ${databaseAddress}.

FreeMarker evaluates all expressions between ${} which may be inappropriate in certain kinds of files. To include the literal ${value} in a script you might:

• specify a raw string literal: ${r"${value}"}
• use the noparse directive: <#noparse>${value}</#noparse>
• use FreeMarker's alternative syntax.

A common pattern for templating Bash files is to set environment variables at the top of the script and to surround the rest of its contents with noparse. For example:

GREETING=${config['greeting']}
NAME=${config['name']}

<#noparse>
# The remainder of the script can be written as normal.
echo "${GREETING}, ${NAME}!"
</#noparse>

Using templates in blueprints

Files can be uploaded at several stages of an entity's lifecycle:

Each key accepts a map of values where a key indicates the source of a file and a value its destination on the instance.

Files can be referenced as URLs. This includes support for:

• classpath://mypath/myfile.bat, which looks for the given (fully qualified) resource on the Brooklyn classpath or inside the bundle, if using the OSGi version of Brooklyn with a catalog blueprint.
• file://, which looks for the given file on the Brooklyn server, and
• http://, which requires the file to be accessible from the Brooklyn instance.

Destinations may be absolute or relative. Absolute paths need not exist beforehand, but Brooklyn's SSH user must have sufficient permission to create all parent directories and the file itself. Relative paths are copied as described in the table above.

Example

files.preinstall:
  # Reference a fixed resource
  classpath://com/acme/installAcme.ps1: C:\\acme\installAcme.ps1
  # Inject the source from a config key
  $brooklyn:config("acme.conf"): C:\\acme\acme.conf

Windows notes

• When writing scripts for Windows ensure that each line ends with "\r\n", rather than just "\n".
• The backslash character (\) must be escaped in paths. For example: C:\\install7zip.ps1.