You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by dr...@apache.org on 2017/06/16 15:22:03 UTC
[23/28] brooklyn-docs git commit: Promote templating files from WinRM
page to its own section
Promote templating files from WinRM page to its own section
(cherry picked from commit 54caed76924688ffca78831fa8bcd40907cfa8d5)
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/73690d64
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/73690d64
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/73690d64
Branch: refs/heads/0.11.x
Commit: 73690d64698569ada9ab730a8751bf0f0aac1c26
Parents: 122fe40
Author: Sam Corbett <sa...@cloudsoftcorp.com>
Authored: Wed May 10 13:08:59 2017 +0100
Committer: Richard Downer <ri...@apache.org>
Committed: Wed May 31 15:32:47 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/73690d64/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/73690d64/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