You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by al...@apache.org on 2016/06/06 22:46:25 UTC
[1/2] brooklyn-docs git commit: BROOKLYN-286: docs for entity-config
merging
Repository: brooklyn-docs
Updated Branches:
refs/heads/master 78ee70537 -> 7e8166fa1
BROOKLYN-286: docs for entity-config merging
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/c422a10f
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/c422a10f
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/c422a10f
Branch: refs/heads/master
Commit: c422a10fb3867783b1b98cf9d1e59af949e6e723
Parents: 74a25d1
Author: Aled Sage <al...@gmail.com>
Authored: Mon Jun 6 15:16:20 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Mon Jun 6 23:44:49 2016 +0100
----------------------------------------------------------------------
guide/yaml/entity-configuration.md | 303 ++++++++++++++++++++++++++++++++
guide/yaml/index.md | 1 +
2 files changed, 304 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c422a10f/guide/yaml/entity-configuration.md
----------------------------------------------------------------------
diff --git a/guide/yaml/entity-configuration.md b/guide/yaml/entity-configuration.md
new file mode 100644
index 0000000..fcd0511
--- /dev/null
+++ b/guide/yaml/entity-configuration.md
@@ -0,0 +1,303 @@
+---
+title: Entity Configuration
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Within a blueprint or catalog item, entities can be configured. The rules for setting this
+configuration, including when composing and extending existing entities, is described in this
+section.
+
+
+### Basic Configuration
+
+Within a YAML file, entity configuration should be supplied within a `brooklyn.config` map. It is
+also possible to supply configuration at the top-level of the entity. However, that approach is
+discouraged as it can sometimes be ambiguous (e.g. if the config key is called "name" or "type"),
+and also it does not work in all contexts such as for an enricher's configuration.
+
+A simple example is shown below:
+
+{% highlight yaml %}
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+ brooklyn.config:
+ webapp.enabledProtocols: http
+ http.port: 9080
+ wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-webapp/0.9.0/brooklyn-example-hello-world-webapp-0.9.0.war
+{% endhighlight %}
+
+If no config value is supplied, the default for that config key will be used. For example,
+`http.port` would default to 8080 if not explicitly supplied.
+
+Some config keys also have a short-form (e.g. `httpPort` instead of `http.port` would also work
+in the YAML example above). However, that approach is discouraged as it does not work in all contexts
+such as for inheriting configuration from a parent entity.
+
+
+### Configuration in a Catalog Item
+
+When defining an entity in the catalog, it can include configuration values like any other
+blueprint. It can also explicitly declare config keys. For details of how to write and add
+catalog items, see [Catalog]({{ site.path.guide }}/ops/catalog/). For more details of
+declaring config keys, see the section ["Declaring New Config Keys" in Custom Entities](custom-entities.html).
+
+The example below illustrates the principles:
+
+{% highlight yaml %}
+brooklyn.catalog:
+ items:
+ - id: entity-config-example
+ displayName: Entity Config Example
+ item:
+ type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+ brooklyn.parameters:
+ - name: custom.message
+ type: string
+ default: Hello
+ brooklyn.config:
+ shell.env:
+ MESSAGE: $brooklyn:config("custom.message")
+ launch.command: |
+ echo "My example launch command: $MESSAGE"
+ checkRunning.command: |
+ echo "My example checkRunning command: $MESSAGE"
+{% endhighlight %}
+
+Once added to the catalog, it can be used with the simple blueprint below (substituting the location
+of your choice). Because no configuration has been overridden, this will use the default value
+for `custom.message`, and will use the given values for `launch.command` and `checkRunning.command`:
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: entity-config-example
+{% endhighlight %}
+
+
+### Inheriting Configuration from a Parent Entity
+
+Configuration passed to an entity is inherited by all child entities, unless explicitly overridden.
+This can simplify some blueprints, but also care should be taken to ensure default values are not
+accidentally overridden.
+
+In the example below, the `wars.root` config key is inherited by all TomcatServer entities created
+under the cluster, so they will use that war:
+
+{% highlight yaml %}
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+ brooklyn.config:
+ wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-webapp/0.9.0/brooklyn-example-hello-world-webapp-0.9.0.war
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+{% endhighlight %}
+
+
+### Inheriting Configuration from Super-type
+
+When using an entity from the catalog, its configuration values can be overridden. For example,
+consider the `entity-config-example` added to the catalog in the section "Configuration in a
+Catalog Item". We can override these values:
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: entity-config-example
+ brooklyn.config:
+ custom.message: Goodbye
+ launch.command: |
+ echo "Different example launch command: $MESSAGE"
+{% endhighlight %}
+
+If not overridden, then the existing values from the super-type will be used.
+
+
+### Configuration Precedence
+
+There are several places that a configuration value can come from. If different values are
+specified in multiple places, then the order of precedence is as listed below:
+
+1. Configuration on the entity itself
+2. Inherited configuration from the super-type
+3. Inherited configuration from the parent entity (or grandparent, etc)
+4. The config key's default value
+
+
+### Merging Configuration Values
+
+For some configuration values, the most logical behaviour is to merge the configuration value
+with that in the super-type. This depends on the type and meaning of the config key, and is thus
+an option when defining the config key.
+
+Currently it is only supported for merging config keys of type Map.
+
+Some common config keys will default to merging the values from the super-type. These config keys
+include those below. The value is merged with that of its super-type (but will not be merged with
+the value on a parent entity):
+
+* `shell.env`: a map of environment variables to pass to the runtime shell
+* `files.preinstall`: a mapping of files, to be copied before install, to destination name relative to installDir
+* `templates.preinstall`: a mapping of templates, to be filled in and copied before pre-install, to destination name relative to installDir
+* `files.install`: a mapping of files, to be copied before install, to destination name relative to installDir
+* `templates.install`: a mapping of templates, to be filled in and copied before install, to destination name relative to installDir
+* `files.runtime`: a mapping of files, to be copied before customisation, to destination name relative to runDir
+* `templates.runtime`: a mapping of templates, to be filled in and copied before customisation, to destination name relative to runDir
+* `provisioning.properties`: custom properties to be passed in when provisioning a new machine
+
+A simple example of merging `shell.env` is shown below (building on the `entity-config-example` in
+the previous section). The environment variables will include the `MESSAGE` set in the super-type
+and the `MESSAGE2` set here:
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: entity-config-example
+ brooklyn.config:
+ shell.env:
+ MESSAGE2: Goodbye
+ launch.command: |
+ echo "Different example launch command: $MESSAGE and $MESSAGE2"
+{% endhighlight %}
+
+To explicitly remove a value from the super-type's map (rather than adding to it), a blank entry
+can be defined.
+
+When defining a new config key, the exact semantics for inheritance can be defined. There are
+separate options for `inheritance.type` and `inheritance.parent` (the former determines how
+config inheritance from the super-type is handles; the latter determines how inheritance
+from the parent entity is handled. The possible values are:
+
+* `deep_merge`: the inherited and the given value should be merged; maps within the map will also be merged
+* `always`: the inherited value should be used, unless explicitly overridden by the entity
+* `none`: the value should not be inherited; if there is no explicit value on the entity then the default value will be used
+
+Below is a (contrived!) example of inheriting the `example.map` config key. When using this entity
+in a blueprint, the entity's config will be merged with that defined in the super-type, and the
+parent entity's value will never be inherited:
+
+{% highlight yaml %}
+brooklyn.catalog:
+ items:
+ - id: entity-config-example
+ version: 1.1.0-SNAPSHOT
+ displayName: Entity Config Example
+ item:
+ type: org.apache.brooklyn.entity.machine.MachineEntity
+ brooklyn.parameters:
+ - name: example.map
+ type: java.util.Map
+ inheritance.type: deep_merge
+ inheritance.parent: none
+ default:
+ MESSAGE_IN_DEFAULT: InDefault
+ brooklyn.config:
+ example.map:
+ MESSAGE: Hello
+{% endhighlight %}
+
+The blueprints below demonstrate the various permutations for setting configuration for the
+config `example.map`. This can be inspected by looking at the entity's config. The config
+we see for app1 is the inherited `{MESSAGE: "Hello"}`; in app2 we define additional configuration,
+which will be merged to give `{MESSAGE: "Hello", MESSAGE_IN_CHILD: "InChild"}`; in app3, the
+config from the parent is not inherited because there is an explicit inheritance.parent of "none",
+so it just has the value `{MESSAGE: "Hello"}`; in app4 again the parent's config is ignored,
+with the super-type and entity's config being merged to give `{MESSAGE: "Hello", MESSAGE_IN_CHILD: "InChild"}`.
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app1
+ brooklyn.children:
+ - type: entity-config-example
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app2
+ brooklyn.children:
+ - type: entity-config-example
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_CHILD: InChild
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app3
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_PARENT: InParent
+ brooklyn.children:
+ - type: entity-config-example
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+ name: app4
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_PARENT: InParent
+ brooklyn.children:
+ - type: entity-config-example
+ brooklyn.config:
+ example.map:
+ MESSAGE_IN_CHILD: InChild
+{% endhighlight %}
+
+A limitations of `inheritance.parent` is when inheriting values from parent and grandparent
+entities: a value specified on the parent will override (rather than be merged with) the
+value on the grandparent.
+
+
+### Entity provisioning.properties: Overriding and Merging
+
+An entity (which extends `SoftwareProcess`) can define a map of `provisioning.properties`. If
+the entity then provisions a location, it passes this map of properties to the location for
+obtaining the machine. These properties will override and augment the configuration on the location
+itself.
+
+When deploying to a jclouds location, one can specify `templateOptions` (of type map). Rather than
+overriding, these will be merged with any templateOptions defined on the location.
+
+In the example below, the VM will be provisioned with minimum 2G ram and minimum 2 cores. It will
+also use the merged template options value of
+`{placementGroup: myPlacementGroup, securityGroupIds: sg-000c3a6a}`:
+
+{% highlight yaml %}
+location:
+ aws-ec2:us-east-1:
+ minRam: 2G
+ templateOptions:
+ placementGroup: myPlacementGroup
+services:
+- type: org.apache.brooklyn.entity.machine.MachineEntity
+ brooklyn.config:
+ provisioning.properties:
+ minCores: 2
+ templateOptions:
+ securityGroupIds: sg-000c3a6a
+{% endhighlight %}
+
+The merging of `templateOptions` is shallow (i.e. maps within the `templateOptions` are not merged).
+In the example below, the `userMetadata` value within `templateOptions` will be overridden by the
+entity's value, rather than the maps being merged; the value used when provisioning will be
+`{key2: val2}`:
+
+{% highlight yaml %}
+location:
+ aws-ec2:us-east-1:
+ templateOptions:
+ userMetadata:
+ key1: val1
+services:
+- type: org.apache.brooklyn.entity.machine.MachineEntity
+ brooklyn.config:
+ provisioning.properties:
+ userMetadata:
+ key2: val2
+{% endhighlight %}
+
+
+
+### Merging Location, Policy and Enricher Configuration Values
+
+A current limitation is that `inheritance.type` is not supported for configuration of locations,
+policies and enrichers. The current behaviour is that config is not inherited.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/c422a10f/guide/yaml/index.md
----------------------------------------------------------------------
diff --git a/guide/yaml/index.md b/guide/yaml/index.md
index 43d3b25..def24c1 100644
--- a/guide/yaml/index.md
+++ b/guide/yaml/index.md
@@ -7,6 +7,7 @@ children:
- configuring-vms.md
- clusters.md
- multiple-services.md
+- entity-configuration.md
- clusters-and-policies.md
- blueprinting-tips.md
- custom-entities.md
[2/2] brooklyn-docs git commit: This closes #75
Posted by al...@apache.org.
This closes #75
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/7e8166fa
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/7e8166fa
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/7e8166fa
Branch: refs/heads/master
Commit: 7e8166fa1ca681ab84c8b86a8f4f9c1136b95e52
Parents: 78ee705 c422a10
Author: Aled Sage <al...@gmail.com>
Authored: Mon Jun 6 23:46:15 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Mon Jun 6 23:46:15 2016 +0100
----------------------------------------------------------------------
guide/yaml/entity-configuration.md | 303 ++++++++++++++++++++++++++++++++
guide/yaml/index.md | 1 +
2 files changed, 304 insertions(+)
----------------------------------------------------------------------