brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rdowner <...@git.apache.org>
Subject [GitHub] brooklyn-docs pull request #178: Guide to template files
Date Mon, 08 May 2017 13:49:28 GMT
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.
---

Mime
View raw message