You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by sjcorbett <gi...@git.apache.org> on 2017/05/05 22:43:29 UTC
[GitHub] brooklyn-docs pull request #178: Guide to template files
GitHub user sjcorbett opened a pull request:
https://github.com/apache/brooklyn-docs/pull/178
Guide to template files
A full guide to using template files in blueprints.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/sjcorbett/brooklyn-docs template-guide
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/brooklyn-docs/pull/178.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #178
----
commit df17cee484a7a713870cd942027caeadc84021a1
Author: Sam Corbett <sa...@cloudsoftcorp.com>
Date: 2017-05-05T22:34:45Z
Promote templating files from WinRM page to its own section
commit 25273a7b894e4bdddd3d4aedeb8033f882d7f656
Author: Sam Corbett <sa...@cloudsoftcorp.com>
Date: 2017-05-05T22:36:41Z
Brooklyn is not AMP
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs issue #178: Guide to template files
Posted by sjcorbett <gi...@git.apache.org>.
Github user sjcorbett commented on the issue:
https://github.com/apache/brooklyn-docs/pull/178
@drigodwin @rdowner thanks. I've addressed all your comments.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs pull request #178: Guide to template files
Posted by drigodwin <gi...@git.apache.org>.
Github user drigodwin commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115227186
--- Diff: guide/blueprints/config-files.md ---
@@ -0,0 +1,78 @@
+---
+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. One simple way
+to achieve this is to compile the support files into a .jar, which is then added to Brooklyn's 'dropins' folder.
+Alternatively, an OSGi bundle can be used, referenced from the catalog item.
--- End diff --
Perhaps mention that these methods are specific to the way brooklyn is launched.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs pull request #178: Guide to template files
Posted by drigodwin <gi...@git.apache.org>.
Github user drigodwin commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115720672
--- Diff: guide/blueprints/config-files.md ---
@@ -0,0 +1,104 @@
+---
+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:
+
+```
--- End diff --
The website uses kramdown not markdown, the three backticks doesn't display in the same way. It's better to use four spaces before each line as in the example section.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs pull request #178: Guide to template files
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/brooklyn-docs/pull/178
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs pull request #178: Guide to template files
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115250946
--- Diff: guide/blueprints/config-files.md ---
@@ -0,0 +1,78 @@
+---
+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. One simple way
+to achieve this is to compile the support files into a .jar, which is then added to Brooklyn's 'dropins' folder.
+Alternatively, an OSGi bundle can be used, referenced from the catalog item.
+
+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.
+
+
+### Using files
+
+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 the backslash character
+(\\) must be escaped when using Windows. For example: `C:\\install7zip.ps1`.
+
+Files can be uploaded at several stages of an entity's lifecycle:
+
+| Config key | Copied before lifecycle phase | Templated |
+|------------------------|-------------------------------|-----------|
+| `files.preinstall` | Pre-install | ✕ |
+| `files.install` | Install | ✕ |
+| `files.customize` | Customize | ✕ |
+| `files.runtime` | Launch | ✕ |
+| `templates.preinstall` | Pre-install | ✓ |
+| `templates.install` | Install | ✓ |
+| `templates.customize` | Customize | ✓ |
+| `templates.runtime` | Launch | ✓ |
+
+
+### Template substitutions
+
+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). 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}`.
+
+
+### 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
--- End diff --
I'd also like to see described how to install files to INSTALL_DIR and/or RUN_DIR - do I just omit the path component?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs pull request #178: Guide to template files
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115251215
--- Diff: guide/blueprints/config-files.md ---
@@ -0,0 +1,78 @@
+---
+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. One simple way
+to achieve this is to compile the support files into a .jar, which is then added to Brooklyn's 'dropins' folder.
+Alternatively, an OSGi bundle can be used, referenced from the catalog item.
+
+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.
+
+
+### Using files
+
+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 the backslash character
+(\\) must be escaped when using Windows. For example: `C:\\install7zip.ps1`.
+
+Files can be uploaded at several stages of an entity's lifecycle:
+
+| Config key | Copied before lifecycle phase | Templated |
+|------------------------|-------------------------------|-----------|
+| `files.preinstall` | Pre-install | ✕ |
+| `files.install` | Install | ✕ |
+| `files.customize` | Customize | ✕ |
+| `files.runtime` | Launch | ✕ |
+| `templates.preinstall` | Pre-install | ✓ |
+| `templates.install` | Install | ✓ |
+| `templates.customize` | Customize | ✓ |
+| `templates.runtime` | Launch | ✓ |
+
+
+### Template substitutions
+
+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). 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` |
--- End diff --
How do I insert a literal `${ABC}`? (Important in shell scripts, for example)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs pull request #178: Guide to template files
Posted by rdowner <gi...@git.apache.org>.
Github user rdowner commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115236606
--- Diff: guide/blueprints/config-files.md ---
@@ -0,0 +1,78 @@
+---
+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. One simple way
+to achieve this is to compile the support files into a .jar, which is then added to Brooklyn's 'dropins' folder.
+Alternatively, an OSGi bundle can be used, referenced from the catalog item.
+
+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.
+
+
+### Using files
+
+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.
--- End diff --
"... or inside the bundle, if using the OSGI version of Brooklyn with catalog blueprint" (or similar wording)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs issue #178: Guide to template files
Posted by sjcorbett <gi...@git.apache.org>.
Github user sjcorbett commented on the issue:
https://github.com/apache/brooklyn-docs/pull/178
@rdowner I think this is something you were looking at previously.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] brooklyn-docs pull request #178: Guide to template files
Posted by drigodwin <gi...@git.apache.org>.
Github user drigodwin commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115227463
--- Diff: guide/blueprints/config-files.md ---
@@ -0,0 +1,78 @@
+---
+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. One simple way
+to achieve this is to compile the support files into a .jar, which is then added to Brooklyn's 'dropins' folder.
+Alternatively, an OSGi bundle can be used, referenced from the catalog item.
+
+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.
+
+
+### Using files
+
+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 the backslash character
--- End diff --
What's the configuration key? or perhaps an example of one.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---