Promote templating files from WinRM page to its own section
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/54caed76 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/54caed76 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/54caed76 Branch: refs/heads/master Commit: 54caed76924688ffca78831fa8bcd40907cfa8d5 Parents: 7337fa5 Author: Sam Corbett <[email protected]> Authored: Wed May 10 13:08:59 2017 +0100 Committer: Sam Corbett <[email protected]> Committed: Wed May 10 13:08:59 2017 +0100 ---------------------------------------------------------------------- guide/blueprints/config-files.md | 102 ++++++++++++++++++++++++++++++++++ guide/blueprints/winrm/index.md | 41 -------------- 2 files changed, 102 insertions(+), 41 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/54caed76/guide/blueprints/config-files.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/config-files.md b/guide/blueprints/config-files.md new file mode 100644 index 0000000..f92aeb8 --- /dev/null +++ b/guide/blueprints/config-files.md @@ -0,0 +1,102 @@ +--- +title: Uploading Script and Configuration Files +layout: website-normal +toc: ../guide_toc.json +categories: [use, guide, defining-applications] +--- + +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](http://freemarker.org) +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: + +| Substitution | Effect | +|---------------------------|--------------------------------------------------------------------| +| `${config['key']}` | Equivalent to `entity.config().get(key)` | +| `${attribute['key']}` | Equivalent to `entity.sensors().get(key)` | +| `${mgmt['key']}` | Loads the value for `key` from the management context's properties | +| `${entity.foo}` | FreeMarker calls `getFoo` on the entity | +| `${driver.foo}` | FreeMarker calls `getFoo` on the entity's [driver](http://brooklyn.apache.org/v/latest/java/entity.html#things-to-know) | +| `${location.foo}` | FreeMarker calls `getFoo` on the entity's location | +| `${javaSysProps.foo.bar}` | Loads the system property named `foo.bar` | + +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](http://freemarker.org/docs/dgui_template_exp.html#dgui_template_exp_direct_string): + `${r"${value}"}` + * use the [noparse](http://freemarker.org/docs/ref_directive_noparse.html) directive: `<#noparse>${value}</#noparse>` + * use FreeMarker's [alternative syntax](http://freemarker.org/docs/dgui_misc_alternativesyntax.html). + +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: + +| Config key | Copied before lifecycle phase | Templated | Relative to | +|------------------------|-------------------------------|-----------|--------------| +| `files.preinstall` | Pre-install | â | `installDir` | +| `files.install` | Install | â | `installDir` | +| `files.customize` | Pre-customize command | â | `installDir` | +| `files.runtime` | Pre-launch command | â | `run.dir` | +| `templates.preinstall` | Pre-install | â | `installDir` | +| `templates.install` | Install | â | `installDir` | +| `templates.customize` | Pre-customize command | â | `installDir` | +| `templates.runtime` | Pre-launch command | â | `run.dir` | + +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`. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/54caed76/guide/blueprints/winrm/index.md ---------------------------------------------------------------------- diff --git a/guide/blueprints/winrm/index.md b/guide/blueprints/winrm/index.md index 0d29dbc..6155c60 100644 --- a/guide/blueprints/winrm/index.md +++ b/guide/blueprints/winrm/index.md @@ -199,47 +199,6 @@ Or alternatively: Note the quotes around the command. This is because the "&" has special meaning in a YAML value. -### Uploading Script and Configuration Files - -Often, blueprints will 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. One simple way -to achieve this is to compile the support files into a .jar, which is then added to AMP's 'dropins' folder. Alternatively, -an OSGi bundle can be used, referenced from the catalog item. - -Ensure that these scripts end each line with "\r\n", rather than just "\n". - -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](http://freemarker.org) -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. - -Templated files (be they configuration files or scripts) gives 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). A common substitution is of the form `${config['mykey']}`. -This looks up a config key (in this case named "mykey") and will insert the value into the file. -Another common substitution is is of the form `${attribute['myattribute']}` - this looks up the -attribute named "myattribute" of this entity. - -Files can be referenced as URLs. This includes support for things like `classpath://mypath/myfile.bat`. -This looks for the given (fully qualified) resource on the Brooklyn classpath. - -The destination for the file upload is specified in the entity's configuration. Note that "\" must -be escaped. For example `"C:\\install7zip.ps1"`. - -A list of plain files to be uploaded can be configured under `files.preinstall`, `files.install` and -`files.runtime`. These are uploaded respectively prior to executing the `pre.install.command`, -prior to `install.command` and prior to `pre.launch.command`. - -A list of templated files to be uploaded can be configured under `templates.preinstall`, `templates.install` -and `templates.runtime`. The times these are uploaded is as for the plain files. The templates -substitutions will be resolved only at the point when the file is to be uploaded. - -For example: - - files.preinstall: - - classpath://com/acme/installAcme.ps1 - - classpath://com/acme/acme.conf - ### Parameterised Scripts Calling parameterised Batch and Powershell scripts is done in the normal Windows way - see
