brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From m4rkmcke...@apache.org
Subject [11/14] brooklyn-docs git commit: Refactor Blueprinting
Date Wed, 19 Apr 2017 08:56:40 GMT
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/index.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/index.md b/guide/blueprints/chef/index.md
new file mode 100644
index 0000000..f0fa3d0
--- /dev/null
+++ b/guide/blueprints/chef/index.md
@@ -0,0 +1,18 @@
+---
+title: Chef in YAML Blueprints
+layout: website-normal
+children:
+- about-chef.md
+- creating-blueprints.md
+- writing-chef.md
+- advanced-chef-integration.md
+---
+
+This guide describes how Brooklyn entities can be easily created from Chef cookbooks.
+As of this writing (May 2014) some of the integration points are under active development,
+and comments are welcome.
+A plan for the full integration is online [here](https://docs.google.com/a/cloudsoftcorp.com/document/d/18ZwzmncbJgJeQjnSvMapTWg6N526cvGMz5jaqdkxMf8).  
+
+This guide assumes you are familiar with the basics of [creating YAML blueprints](../).
+
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/chef/writing-chef.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/chef/writing-chef.md b/guide/blueprints/chef/writing-chef.md
new file mode 100644
index 0000000..671d961
--- /dev/null
+++ b/guide/blueprints/chef/writing-chef.md
@@ -0,0 +1,79 @@
+---
+title: Writing Chef for Blueprints
+title_in_menu: Writing Chef for Blueprints
+layout: website-normal
+---
+
+## Making it Simpler
+
+The example we've just seen shows how existing Chef cookbooks can be
+used as the basis for entities.  If you're *writing* the Chef recipes, 
+there are a few simple techniques we've established with the Chef community
+which make blueprints literally as simple as:
+
+    - type: chef:mysql
+      brooklyn.config:
+        mysql_password: p4ssw0rd
+        pid_file: /var/run/mysqld/mysqld.pid
+
+
+### Some Basic Conventions
+
+* **A `start` recipe**:
+  The first step is to provide a `start` recipe in `recipes/start.rb`;
+  if no `launch_run_list` is supplied, this is what will be invoked to launch the entity.
+  It can be as simple as a one-line file:
+
+      include_recipe 'mysql::server'
+
+* **Using `brooklyn.config`**:
+  All the `brooklyn.config` is passed to Chef as node attributes in the `node['brooklyn']['config']` namespace.
+  Thus if the required attributes in the mysql recipe are set to take a value set in
+  `node['brooklyn']['config']['mysql_password']`, you can dispense with the `launch_attributes` section.
+
+
+## Using Chef Server
+
+The examples so far have not required Chef Server, so they will work without any external
+Chef dependencies (besides the built-in install from `https://www.opscode.com/chef/install.sh`
+and the explicitly referenced cookbooks).  If you use Chef Server, however, you'll want your
+managed nodes to be integrated with it.  This is easy to set up, with a few options:
+
+If you have `knife` set up in your shell environment, the Brooklyn Chef support will use it
+by default. If the recipes are installed in your Chef server, you can go ahead and remove
+the `cookbooks_url` section!
+
+Use of `solo` or `knife` can be forced by setting the `chef_mode` flag (`brooklyn.chef.mode` config key)
+to either of those values.  (It defaults to `autodetect`, which will use `knife` if it is on the path and satisfies
+sanity checks).
+
+If you want to specify a different configuration, there are a number of config keys you can use:
+
+* `brooklyn.chef.knife.executableFile`: this should be point to the knife binary to use
+* `brooklyn.chef.knife.configFile`: this should point to the knife configuration to use
+* `brooklyn.chef.knife.setupCommands`: an optional set of commands to run prior to invoking knife,
+  for example to run `rvm` to get the right ruby version on the Brooklyn server
+
+If you're interested in seeing the Chef REST API be supported directly (without knife),
+please let us know.  We'd like to see this too, and we'll help you along the way!
+ 
+
+## Tips and Tricks
+
+To help you on your way writing Chef blueprints, here are a handful of pointers
+particularly useful in this context:
+
+* Configuration keys can be inherited from the top-level and accessed using `$brooklyn:entity('id').config('key_name')`.
+  An example of this is shown in the `mysql-chef.yaml` sample recipe contained in the Brooklyn code base
+  and [here](example_yaml/mysql-chef-2.yaml) for convenience.
+  Here, `p4ssw0rd` is specified only once and then used for all the attributes required by the stock mysql cookbook.  
+
+* Github tarball downloads! You'll have noticed these in the example already, but they are so useful we thought
+  we'd call them out again. Except when you're developing, we recommend using specific tagged versions rather than master.
+
+* The usual machine `provisioning.properties` are supported with Chef blueprints, 
+  so you can set things like `minRam` and `osFamily`
+
+* To see more configuration options, and understand the ones presented here in more detail, see the javadoc or
+  the code for the class `ChefConfig` in the Brooklyn code base.
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/clusters-and-policies.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/clusters-and-policies.md b/guide/blueprints/clusters-and-policies.md
new file mode 100644
index 0000000..d40c97f
--- /dev/null
+++ b/guide/blueprints/clusters-and-policies.md
@@ -0,0 +1,42 @@
+---
+title: Clusters and Policies
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Now let's bring the concept of the "cluster" back in.
+We could wrap our appserver in the same `DynamicCluster` we used earlier,
+although then we'd need to define and configure the load balancer.
+But another blueprint, the `ControlledDynamicWebAppCluster`, does this for us.
+It takes the same `dynamiccluster.memberspec`, so we can build a fully functional elastic 3-tier
+deployment of our `hello-world-sql` application as follows:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-clustered-w-db.yaml %}
+{% endhighlight %}
+
+This sets up Nginx as the controller by default, but that can be configured
+using the `controllerSpec` key. In fact, JBoss is the default appserver,
+and because configuration in Brooklyn is inherited by default,
+the same blueprint can be expressed more concisely as:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-clustered-w-db-concise.yaml %}
+{% endhighlight %}
+ 
+The other nicety supplied by the `ControlledDynamicWebAppCluster` blueprint is that
+it aggregates sensors from the appserver, so we have access to things like
+`webapp.reqs.perSec.windowed.perNode`.
+These are convenient for plugging in to policies!
+We can set up our blueprint to do autoscaling based on requests per second
+(keeping it in the range 10..100, with a maximum of 5 appserver nodes)
+as follows: 
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-policy.yaml %}
+{% endhighlight %}
+
+Use your favorite load-generation tool (`jmeter` is one good example) to send a huge
+volume of requests against the server and see the policies kick in to resize it.
+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/clusters.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/clusters.md b/guide/blueprints/clusters.md
new file mode 100644
index 0000000..4c1312c
--- /dev/null
+++ b/guide/blueprints/clusters.md
@@ -0,0 +1,34 @@
+---
+title: Clusters, Specs, and Composition
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+What if you want multiple machines?
+
+One way is just to repeat the `- type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess` block,
+but there's another way which will keep your powder [DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself):
+
+{% highlight yaml %}
+{% readj example_yaml/cluster-vm.yaml %}
+{% endhighlight %}
+
+Here we've composed the previous blueprint introducing some new important concepts, the `DynamicCluster`
+the `$brooklyn` DSL, and the "entity-spec".  Let's unpack these. 
+
+The `DynamicCluster` creates a set of homogeneous instances.
+At design-time, you specify an initial size and the specification for the entity it should create.
+At runtime you can restart and stop these instances as a group (on the `DynamicCluster`) or refer to them
+individually. You can resize the cluster, attach enrichers which aggregate sensors across the cluster, 
+and attach policies which, for example, replace failed members or resize the cluster dynamically.
+
+The specification is defined in the `dynamiccluster.memberspec` key.  As you can see it looks very much like the
+previous blueprint, with one extra line.  Entries in the blueprint which start with `$brooklyn:`
+refer to the Brooklyn DSL and allow a small amount of logic to be embedded
+(if there's a lot of logic, it's recommended to write a blueprint YAML plugin or write the blueprint itself
+as a plugin, in Java or a JVM-supported language).  
+
+In this case we want to indicate that the parameter to `dynamiccluster.memberspec` is an entity specification
+(`EntitySpec` in the underlying type system); the `entitySpec` DSL command will do this for us.
+The example above thus gives us 5 VMs identical to the one we created in the previous section.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/configuring-vms.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/configuring-vms.md b/guide/blueprints/configuring-vms.md
new file mode 100644
index 0000000..e7e7f47
--- /dev/null
+++ b/guide/blueprints/configuring-vms.md
@@ -0,0 +1,31 @@
+---
+title: Configuring VMs
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Another simple blueprint will just create a VM which you can use, without any software installed upon it:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-vm.yaml %}
+{% endhighlight %}
+
+
+*We've omitted the `location` section here and in many of the examples below;
+add the appropriate choice when you paste your YAML. Note that the `provisioning.properties` will be
+ignored if deploying to `localhost` or `byon` fixed-IP machines.* 
+
+This will create a VM with the specified parameters in your choice of cloud.
+In the GUI (and in the REST API), the entity is called "VM",
+and the hostname and IP address(es) are reported as [sensors]({{ site.path.guide }}/concepts/entities.html).
+There are many more `provisioning.properties` supported here,
+including:
+
+* a `user` to create (if not specified it creates the same username as `brooklyn` is running under) 
+* a `password` for him or a `publicKeyFile` and `privateKeyFile` (defaulting to keys in `~/.ssh/id_rsa{.pub,}` and no password,
+  so if you have keys set up you can immediately ssh in!)
+* `machineCreateAttempts` (for dodgy clouds, and they nearly all fail occasionally!) 
+* and things like `imageId` and `userMetadata` and disk and networking options (e.g. `autoAssignFloatingIp` for private clouds)
+
+For more information, see [Operations: Locations]({{ site.path.guide }}/locations/index.html).

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/creating-yaml.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/creating-yaml.md b/guide/blueprints/creating-yaml.md
new file mode 100644
index 0000000..6f91784
--- /dev/null
+++ b/guide/blueprints/creating-yaml.md
@@ -0,0 +1,78 @@
+---
+title: The Basic Structure
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+## A First Blueprint
+
+The easiest way to write a blueprint is as a YAML file.
+This follows the  <a href="https://www.oasis-open.org/committees/camp/">OASIS CAMP</a> plan specification, 
+with some extensions described below.
+(A [YAML reference](yaml-reference.html) has more information,
+and if the YAML doesn't yet do what you want,
+it's easy to add new extensions using your favorite JVM language.)
+
+### The Basic Structure
+
+Here's a very simple YAML blueprint plan, to explain the structure:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver.yaml %}
+{% endhighlight %}
+
+* The `name` is just for the benefit of us humans.
+
+* The `location` specifies where this should be deployed.
+  If you've [set up passwordless localhost SSH access]({{ site.path.guide }}/locations/#localhost) 
+  you can use `localhost` as above, but if not, just wait ten seconds for the next example.
+  
+* The `services` block takes a list of the typed services we want to deploy.
+  This is the meat of the blueprint plan, as you'll see below.
+
+Finally, the clipboard in the top-right corner of the example plan box above (hover your cursor over the box)  lets you easily copy-and-paste into the web-console:
+simply [download and launch]({{ site.path.guide }}/start/running.html) Brooklyn,
+then in the "Create Application" dialog at the web console
+(usually [http://127.0.0.1:8081/](http://127.0.0.1:8081/), paste the copied YAML into the "Yaml" tab of the dialog and press "Finish". 
+There are several other ways to deploy, including `curl` and via the command-line,
+and you can configure users, https, persistence, and more, 
+as described [in the ops guide]({{ site.path.guide }}/ops/).
+
+[![Web Console](web-console-yaml-700.png "YAML via Web Console")](web-console-yaml.png)
+
+
+
+<!--
+TODO building up children entities
+
+-->
+
+
+
+### More Information
+
+Topics to explore next on the topic of YAML blueprints are:
+
+{% include list-children.html %}
+
+Plenty of examples of blueprints exist in the Brooklyn codebase,
+so another starting point is to [`git clone`]({{ site.path.website }}/developers/code/index.html) it
+and search for `*.yaml` files therein.
+
+Brooklyn lived as a Java framework for many years before we felt confident
+to make a declarative front-end, so you can do pretty much anything you want to
+by dropping to the JVM. For more information on Java:
+
+* start with a [Maven archetype]({{site.path.guide}}/blueprints/java/archetype.html)
+* see all [Brooklyn Java guide]({{site.path.guide}}/blueprints/java/) topics
+* look at test cases in the [codebase](https://github.com/apache/brooklyn)
+
+<!-- 
+TODO
+* review some [examples]({{site.path.guide}}/use/examples/index.html)
+-->
+
+You can also come talk to us, on IRC (#brooklyncentral on Freenode) or
+any of the usual [hailing frequencies]({{site.path.website}}/community/),
+as these documents are a work in progress.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/custom-entities.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/custom-entities.md b/guide/blueprints/custom-entities.md
new file mode 100644
index 0000000..88d62ff
--- /dev/null
+++ b/guide/blueprints/custom-entities.md
@@ -0,0 +1,269 @@
+---
+title: Custom Entities
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+So far we've covered how to configure and compose entities.
+There's a large library of blueprints available, but
+there are also times when you'll want to write your own.
+
+For complex use cases, you can write JVM, but for many common situations,
+some of the highly-configurable blueprints make it easy to write in YAML,
+including `bash` and Chef.
+ 
+
+### Vanilla Software using `bash`
+
+The following blueprint shows how a simple script can be embedded in the YAML
+(the `|` character is special YAML which makes it easier to insert multi-line text):
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat.yaml %}
+{% endhighlight %}
+
+This starts a simple `nc` listener on port 4321 which will respond `hello` to the first
+session which connects to it. Test it by running `telnet localhost 4321`
+or opening `http://localhost:4321` in a browser.
+
+Note that it only allows you connect once, and after that it fails.
+This is deliberate! We'll repair this later in this example.
+Until then however, in the *Applications* view you can click the server,
+go to the `Effectors` tab, and click `restart` to bring if back to life.  
+
+This is just a simple script, but it shows how any script can be easily embedded here,
+including a script to download and run other artifacts.
+Many artifacts are already packaged such that they can be downloaded and launched 
+with a simple script, and `VanillaSoftwareProcess` can also be used for them. 
+
+
+#### Downloading Files
+
+We can specify a `download.url` which downloads an artifact 
+(and automatically unpacking TAR, TGZ, and ZIP archives)
+before running `launch.command` relative to where that file is installed (or unpacked),
+with the default `launch.command` being `./start.sh`.
+
+So if we create a file `/tmp/netcat-server.tgz` containing just `start.sh` in the root
+which consists of the two lines in the previous example,
+we can instead write our example as: 
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-file.yaml %}
+{% endhighlight %}
+
+
+#### Port Inferencing
+
+If you're deploying to a cloud machine, a firewall might block the port 4321.
+We can tell Brooklyn to open this port explicitly by specifying `inboundPorts: [ 4321 ]`;
+however a more idiomatic way is to specify a config ending with `.port`,
+such as:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-port.yaml %}
+{% endhighlight %}
+
+The regex for ports to be opened can be configured using
+the config `inboundPorts.configRegex` (which has `.*\.port` as the default value).
+
+Config keys of type `org.apache.brooklyn.api.location.PortRange` (aka `port`)
+have special behaviour: when configuring, you can use range notation `8000-8100` or `8000+` to tell Brooklyn
+to find **one** port matching; this is useful when ports might be in use.
+In addition, any such config key will be opened, 
+irrespective of whether it matches the `inboundPorts.configRegex`. 
+To prevent any inferencing of ports to open, you can set the config `inboundPorts.autoInfer` to `false`.
+
+Furthermore, the port inferencing capability takes in account static `ConfigKey` fields that
+are defined on any Entity sub-class. So, `ConfigKey` fields that are based on `PortRanges` type will
+be also included as required open ports.
+
+Note that in the example above, `netcat.port` must be specified in a `brooklyn.config` block.
+This block can be used to hold any config (including for example the `launch.command`),
+but for convenience Brooklyn allows config keys declared on the underlying type
+to be specified up one level, alongside the type.
+However config keys which are *not* declared on the type *must* be declared in the `brooklyn.config` block. 
+
+
+### Passing custom variables
+
+Blueprint scripts can be parametrised through environment variables, making them reusable in different use-cases.
+Define the variables in the `env` block and then reference them using the standard bash notation:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-env.yaml %}
+{% endhighlight %}
+
+Non-string objects in the `env` map will be serialized to JSON before passing them to the script.
+
+
+#### Declaring New Config Keys
+
+We can define config keys to be presented to the user 
+using the `brooklyn.parameters` block:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-port-parameter.yaml %}
+{% endhighlight %}
+
+The example above will allow a user to specify a message to send back
+and the port where netcat will listen.
+The metadata on these parameters is available at runtime in the UI
+and through the API, and is used when populating a catalog.
+
+The example also shows how these values can be passed as environment variables to the launch command.
+The `$brooklyn:config(...)` function returns the config value supplied or default.
+For the type `port`, an attribute sensor is also created to report the *actual* port used after port inference,
+and so the `$brooklyn:attributeWhenReady(...)` function is used.
+(If `$brooklyn:config("netcat.port")` had been used, `4321+` would be passed as `NETCAT_PORT`.)
+
+This gives us quite a bit more power in writing our blueprint:
+
+* Multiple instances of the server can be launched simultaneously on the same host, 
+  as the `4321+` syntax enables Brooklyn to assign them different ports
+* If this type is added to the catalog, a user can configure the message and the port;
+  we'll show this in the next section
+
+
+#### Using the Catalog and Clustering
+
+The *Catalog* tab allows you to add blueprints which you can refer to in other blueprints.
+In that tab, click *+* then *YAML*, and enter the following:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-catalog.bom %}
+{% endhighlight %}
+
+This is the same example as in the previous section, wrapped according to the catalog YAML requirements,
+with one new block added defining an enricher. An enricher creates a new sensor from other values;
+in this case it will create a `main.uri` sensor by populating a `printf`-style string `"http://%s:%s"`
+with the sensor values.
+
+With this added to the catalog, we can reference the type `netcat-example` when we deploy an application.
+Return to the *Home* or *Applications* tab, click *+*, and submit this YAML blueprint:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-reference.yaml %}
+{% endhighlight %}
+
+This extends the previous blueprint which we registered in the catalog,
+meaning that we don't need to include it each time.
+Here, we've elected to supply our own message, but we'll use the default port.
+More importantly, we can package it for others to consume -- or take items others have built.
+
+We can go further and use this to deploy a cluster,
+this time giving a custom port as well as a custom message: 
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-cluster.yaml %}
+{% endhighlight %}
+
+In either of the above examples, if you explore the tree in the *Applications* view
+and look at the *Summary* tab of any of the server instances, you'll now see the URL where netcat is running.
+But remember, netcat will stop after one run, so you'll only be able to use each link once
+before you have to restart it.  You can also run `restart` on the cluster,
+and if you haven't yet experimented with `resize` on the cluster you might want to do that.
+
+
+#### Determining Successful Launch
+
+One requirement of the launch script is that it store the process ID (PID) in the file
+pointed to by `$PID_FILE`, hence the second line of the script.
+This is because Brooklyn wants to monitor the services under management.
+You'll observe this if you connect to one of the netcat services,
+as the process exits afterwards and Brooklyn sets the entity to an `ON_FIRE` state.
+(You can also test this with a `killall nc` before connecting
+or issueing a `stop` command on the server -- but not on the example,
+as stopping an application root causes it to be removed altogether!) 
+
+There are other options for determining launch: you can set `checkRunning.command` and `stop.command` instead,
+as documented on the javadoc and config keys of the {% include java_link.html class_name="VanillaSoftwareProcess" package_path="org/apache/brooklyn/entity/software/base" project_subpath="software/base" %} class,
+and those scripts will be used instead of checking and stopping the process whose PID is in `$PID_FILE`.
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-more-commands.yaml %}
+{% endhighlight %}
+
+And indeed, once you've run one `telnet` to the server, you'll see that the 
+service has gone "on fire" in Brooklyn -- because the `nc` process stops after one run. 
+
+
+#### Attaching Policies
+
+Besides detecting this failure, Brooklyn policies can be added to the YAML to take appropriate 
+action. A simple recovery here might just to automatically restart the process:
+
+{% highlight yaml %}
+{% readj example_yaml/vanilla-bash-netcat-restarter.yaml %}
+{% endhighlight %}
+
+Autonomic management in Brooklyn often follows the principle that complex behaviours emerge
+from composing simple policies.
+The blueprint above uses one policy to triggering a failure sensor when the service is down,
+and another responds to such failures by restarting the service.
+This makes it easy to configure various aspects, such as to delay to see if the service itself recovers
+(which here we've set to 15 seconds) or to bail out on multiple failures within a time window (which again we are not doing).
+Running with this blueprint, you'll see that the service shows as on fire for 15s after a `telnet`,
+before the policy restarts it. 
+
+
+### Sensors and Effectors
+
+For an even more interesting way to test it, look at the blueprint defining
+[a netcat server and client](example_yaml/vanilla-bash-netcat-w-client.yaml).
+This uses `initializers` to define an effector to `sayHiNetcat` on the `Simple Pinger` client,
+using `env` variables to inject the `netcat-server` location and 
+`parameters` to pass in per-effector data:
+
+      env:
+        TARGET_HOSTNAME: $brooklyn:entity("netcat-server").attributeWhenReady("host.name")
+      brooklyn.initializers:
+      - type: org.apache.brooklyn.core.effector.ssh.SshCommandEffector
+        brooklyn.config:
+          name: sayHiNetcat
+          description: Echo a small hello string to the netcat entity
+          command: |
+            echo $message | nc $TARGET_HOSTNAME 4321
+          parameters:
+            message:
+              description: The string to pass to netcat
+              defaultValue: hi netcat
+
+This blueprint also uses initializers to define sensors on the `netcat-server` entity
+so that the `$message` we passed above gets logged and reported back:
+
+      launch.command: |
+        echo hello | nc -l 4321 >> server-input &
+        echo $! > $PID_FILE
+      brooklyn.initializers:
+      - type: org.apache.brooklyn.core.sensor.ssh.SshCommandSensor
+        brooklyn.config:
+          name: output.last
+          period: 1s
+          command: tail -1 server-input
+
+##### Windows Command Sensor
+
+Like the blueprint above, the following example also uses brooklyn.initializers to define sensors on the entity,
+this time however it is a windows VM and uses `WinRmCommandSensor`.
+
+    - type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess
+      brooklyn.config:
+        launch.command: echo launching
+        checkRunning.command: echo running
+      brooklyn.initializers:
+      - type: org.apache.brooklyn.core.sensor.windows.WinRmCommandSensor
+        brooklyn.config:
+          name: ip.config
+          period: 60s
+          command: hostname
+
+#### Summary
+
+These examples are relatively simple example, but they
+illustrate many of the building blocks used in real-world blueprints,
+and how they can often be easily described and combined in Brooklyn YAML blueprints.
+Next, if you need to drive off-piste, or you want to write tests against these blueprints,
+have a look at, for example, `VanillaBashNetcatYamlTest.java` in the Brooklyn codebase,
+or follow the other references below.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/enrichers.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/enrichers.md b/guide/blueprints/enrichers.md
new file mode 100644
index 0000000..436a423
--- /dev/null
+++ b/guide/blueprints/enrichers.md
@@ -0,0 +1,180 @@
+---
+title: Enrichers
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Enrichers provide advanced manipulation of an entity's sensor values.
+See below for documentation of the stock enrichers available in Apache Brooklyn.
+
+#### Transformer
+
+[`org.apache.brooklyn.enricher.stock.Transformer`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Transformer.html)
+
+Takes a source sensor and modifies it in some way before publishing the result in a new sensor. See below an example using `$brooklyn:formatString`.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Transformer
+  brooklyn.config:
+    enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string")
+    enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets")
+    enricher.targetValue: $brooklyn:formatString("[%s]", $brooklyn:attributeWhenReady("urls.tcp.string"))
+{% endhighlight %}
+
+#### Propagator
+
+[`org.apache.brooklyn.enricher.stock.Propagator`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Propagator.html)
+
+Use propagator to duplicate one sensor as another, giving the supplied sensor mapping.
+The other use of Propagator is where you specify a producer (using `$brooklyn:entity(...)` as below)
+from which to take sensors; in that mode you can specify `propagate` as a list of sensors whose names are unchanged, instead of (or in addition to) this map.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Propagator
+  brooklyn.config:
+    producer: $brooklyn:entity("cluster")
+- type: org.apache.brooklyn.enricher.stock.Propagator
+  brooklyn.config:
+    sensorMapping:
+      $brooklyn:sensor("url"): $brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri")
+{% endhighlight %}
+
+#### Custom Aggregating
+
+[`org.apache.brooklyn.enricher.stock.Aggregator`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Aggregator.html)
+
+Aggregates multiple sensor values (usually across a tier, esp. a cluster) and performs a supplied aggregation method to them to return an aggregate figure, e.g. sum, mean, median, etc.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Aggregator
+  brooklyn.config:
+    enricher.sourceSensor: $brooklyn:sensor("webapp.reqs.perSec.windowed")
+    enricher.targetSensor: $brooklyn:sensor("webapp.reqs.perSec.perNode")
+    enricher.aggregating.fromMembers: true
+    transformation: average
+{% endhighlight %}
+
+There are a number of additional configuration keys available for the Aggregators:
+
+| Configuration Key                 | Default | Description                                                         |
+|-----------------------------------|---------|---------------------------------------------------------------------|
+| enricher.transformation.untyped   | list    | Specifies a transformation, as a function from a collection to the value, or as a string matching a pre-defined named transformation, such as 'average' (for numbers), 'sum' (for numbers), 'isQuorate' (to compute a quorum), or 'list' (the default, putting any collection of items into a list) |
+| quorum.check.type                 |         | The requirement to be considered quorate -- possible values: 'all', 'allAndAtLeastOne', 'atLeastOne', 'atLeastOneUnlessEmpty', 'alwaysHealthy'", "allAndAtLeastOne" |
+| quorum.total.size                 | 1       | The total size to consider when determining if quorate              |
+
+#### Joiner
+
+[`org.apache.brooklyn.enricher.stock.Joiner`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Joiner.html)
+
+Joins a sensor whose output is a list into a single item joined by a separator.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Joiner
+  brooklyn.config:
+    enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list")
+    enricher.targetSensor: $brooklyn:sensor("urls.tcp.string")
+    uniqueTag: urls.quoted.string
+{% endhighlight %}
+
+There are a number of additional configuration keys available for the joiner:
+
+| Configuration Key                 | Default | Description                                                         |
+|-----------------------------------|---------|---------------------------------------------------------------------|
+| enricher.joiner.separator         | ,       | Separator string to insert between each argument                    |
+| enricher.joiner.keyValueSeparator | =       | Separator string to insert between each key-value pair              |
+| enricher.joiner.joinMapEntries    | false   | Whether to add map entries as key-value pairs or just use the value |
+| enricher.joiner.quote             | true    | Whether to bash-escape each parameter and wrap in double-quotes     |
+| enricher.joiner.minimum           | 0       | Minimum number of elements to join; if fewer than this, sets null   |
+| enricher.joiner.maximum           | null    | Maximum number of elements to join (null means all elements taken)  |
+
+####	Delta Enricher
+
+[`org.apache.brooklyn.policy.enricher.DeltaEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/DeltaEnricher.html)
+
+Converts an absolute sensor into a delta sensor (i.e. the difference between the current and previous value)
+
+####	Time-weighted Delta
+
+[`org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/YamlTimeWeightedDeltaEnricher.html)
+
+Converts absolute sensor values into a difference over time. The `enricher.delta.period` indicates the measurement interval.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.YamlTimeWeightedDeltaEnricher
+  brooklyn.config:
+    enricher.sourceSensor: reqs.count
+    enricher.targetSensor: reqs.per_sec
+    enricher.delta.period: 1s
+{% endhighlight %}
+
+####	Rolling Mean
+
+[`org.apache.brooklyn.policy.enricher.RollingMeanEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/RollingMeanEnricher.html)
+
+Transforms a sensor into a rolling average based on a fixed window size. This is useful for smoothing sample type metrics, such as latency or CPU time
+
+#### Rolling Time-window Mean
+
+[`org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/RollingTimeWindowMeanEnricher.html)
+
+Transforms a sensor's data into a rolling average based on a time window. This time window can be specified with the config key `confidenceRequired` - Minimum confidence level (ie period covered) required to publish a rolling average (default `8d`).
+
+#### Http Latency Detector
+
+[`org.apache.brooklyn.policy.enricher.RollingTimeWindowMeanEnricher.HttpLatencyDetector`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/policy/enricher/HttpLatencyDetector.html)
+
+An Enricher which computes latency in accessing a URL, normally by periodically polling that URL. This is then published in the sensors `web.request.latency.last` and `web.request.latency.windowed`.
+
+There are a number of additional configuration keys available for the Http Latency Detector:
+
+| Configuration Key                 | Default | Description                                                          |
+|-----------------------------------|---------|----------------------------------------------------------------------|
+| latencyDetector.url               |         | The URL to compute the latency of                                    |
+| latencyDetector.urlSensor         |         | A sensor containing the URL to compute the latency of                |
+| latencyDetector.urlPostProcessing |         | Function applied to the urlSensor value, to determine the URL to use |
+| latencyDetector.rollup            |         | The window size (in duration) over which to compute                  |
+| latencyDetector.requireServiceUp  | false   | Require the service is up                                            |
+| latencyDetector.period            | 1s      | The period of polling                                                |
+
+#### Combiner
+
+[`org.apache.brooklyn.enricher.stock.Combiner`](https://brooklyn.apache.org/v/latest/misc/javadoc/org/apache/brooklyn/enricher/stock/Combiner.html)
+
+Can be used to combine the values of sensors.  This enricher should be instantiated using `Enrichers.builder().combining(..)`.
+This enricher is only available in Java blueprints and cannot be used in YAML.
+
+#### Note On Enricher Producers
+
+If an entity needs an enricher whose source sensor (`enricher.sourceSensor`) belongs to another entity, then the enricher
+configuration must include an `enricher.producer` key referring to the other entity.
+
+For example, if we consider the Transfomer from above, suppose that `enricher.sourceSensor: $brooklyn:sensor("urls.tcp.list")`
+is actually a sensor on a different entity called `load.balancer`. In this case, we would need to supply an
+`enricher.producer` value.
+
+{% highlight yaml %}
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Transformer
+  brooklyn.config:
+    enricher.producer: $brooklyn:entity("load.balancer")
+    enricher.sourceSensor: $brooklyn:sensor("urls.tcp.string")
+    enricher.targetSensor: $brooklyn:sensor("urls.tcp.withBrackets")
+    enricher.targetValue: |
+      $brooklyn:formatString("[%s]", $brooklyn:attributeWhenReady("urls.tcp.string"))
+{% endhighlight %}
+
+It is important to note that the value supplied to `enricher.producer` must be immediately resolvable. While it would be valid
+DSL syntax to write:
+
+{% highlight yaml %}
+enricher.producer: brooklyn:entity($brooklyn:attributeWhenReady("load.balancer.entity"))
+{% endhighlight %}
+
+(assuming the `load.balancer.entity` sensor returns a Brooklyn entity), this will not function properly because `enricher.producer`
+will unsuccessfully attempt to get the supplied entity immediately.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/entity-configuration.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/entity-configuration.md b/guide/blueprints/entity-configuration.md
new file mode 100644
index 0000000..14561ac
--- /dev/null
+++ b/guide/blueprints/entity-configuration.md
@@ -0,0 +1,548 @@
+---
+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 (i.e. inside the `brooklyn.config` block).
+
+It can also explicitly declare config keys, using the `brooklyn.parameters` block. The example 
+below illustrates the principle:
+
+{% highlight yaml %}
+brooklyn.catalog:
+  items:
+  - id: entity-config-example
+    itemType: entity
+    name: Entity Config Example
+    item:
+      type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+      brooklyn.parameters:
+      - name: custom.message
+        type: string
+        description: Message to be displayed
+        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 %}
+
+For details of how to write and add catalog items, see [Catalog]({{ site.path.guide }}/blueprints/catalog/). 
+
+
+#### Config Key Constraints
+
+The config keys in the `brooklyn.parameters` can also have constraints defined, for what values
+are valid. If more than one constraint is defined, then they must all be satisfied. The constraints 
+can be any of:
+
+* `required`: deployment will fail if no value is supplied for this config key.
+* `regex: ...`: the value will be compared against the given regular expression.
+* A predicate, declared using the DSL `$brooklyn:object`.  
+
+This is illustrated in the example below:
+
+{% highlight yaml %}
+brooklyn.catalog:
+  items:
+  - id: entity-constraint-example
+    itemType: entity
+    name: Entity Config Example
+    item:
+      type: org.apache.brooklyn.entity.stock.BasicEntity
+      brooklyn.parameters:
+      - name: compulsoryExample
+        type: string
+        constraints:
+        - required
+      - name: addressExample
+        type: string
+        constraints:
+        - regex: ^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$
+      - name: numberExample
+        type: double
+        constraints:
+        - $brooklyn:object:
+            type: org.apache.brooklyn.util.math.MathPredicates
+            factoryMethod.name: greaterThan
+            factoryMethod.args:
+            - 0.0
+        - $brooklyn:object:
+            type: org.apache.brooklyn.util.math.MathPredicates
+            factoryMethod.name: lessThan
+            factoryMethod.args:
+            - 256.0
+{% endhighlight %}
+
+An example usage of this toy example, once added to the catalog, is shown below:
+
+{% highlight yaml %}
+services:
+- type: entity-constraint-example
+  brooklyn.config:
+    compulsoryExample: foo
+    addressExample: 1.1.1.1
+    numberExample: 2.0
+{% endhighlight %}
+
+
+### Inheriting Configuration
+
+Configuration can be inherited from a super-type, and from a parent entity in the runtime 
+management hierarchy. This applies to entities and locations. In a future release, this will be
+extended to also apply to policies and enrichers.
+
+When a blueprint author defines a config key, they can explicitly specify the rules for inheritance 
+(both for super/sub-types, and for the runtime management hiearchy). This gives great flexibilty,
+but should be used with care so as not to surprise users of the blueprint.
+
+The default behaviour is outlined below, along with examples and details of how to explilcitly 
+define the desired behaviour.
+
+
+#### Normal 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 runtime type hierarchy
+4. The config key's default value
+
+
+#### 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](#configuration-in-a-catalog-item).
+We can override these values. If not overridden, then the existing values from the super-type will be used:
+
+{% highlight yaml %}
+location: aws-ec2:us-east-1
+services:
+- type: entity-config-example
+  brooklyn.config:
+    custom.message: Goodbye
+    launch.command: |
+      echo "Sub-type launch command: $MESSAGE"
+{% endhighlight %}
+
+
+
+In this example, the `custom.message` overrides the default defined on the config key.
+The `launch.command` overrides the original command. The other config (e.g. `checkRunning.command`)
+is inherited unchanged.
+
+It will write out: `Sub-type launch command: Goodbye`.
+
+
+#### Inheriting Configuration from a Parent in the Runtime Management Hieararchy
+
+Configuration passed to an entity is inherited by all child entities, unless explicitly 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
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+{% endhighlight %}
+
+In the above example, it would be better to have specified the `wars.root` configuration in the 
+`TomcatServer` entity spec, rather than at the top level. This would make it clearer for the reader
+what is actually being configured.
+
+The technique of inherited config can simplify some blueprints, but care should be taken. 
+For more complex (composite) blueprints, this can be difficult to use safely; it relies on 
+knowledge of the internals of the child components. For example, the inherited config 
+may impact multiple sub-components, rather than just the specific entity to be changed.
+This is particularly true when using complex items from the catalog, and when using common config 
+values (e.g. `install.version`).
+
+An alternative approach is to declare the expected configuration options at the top level of the
+catalog item, and then (within the catalog item) explicitly inject those values into the correct
+sub-components. Users of this catalog item would set only those exposed config options, rather 
+than trying to inject config directly into the nested entities.
+
+
+#### DSL Evaluation of Inherited Config
+
+When writing blueprints that rely on inheritance from the runtime management hierarchy, it is 
+important to  understand how config keys that use DSL will be evaluated. In particular, when 
+evaluating a DSL expression, it will be done in the context of the entity declaring the config 
+value (rather than on the entity using the config value).
+
+For example, consider the config value `$brooklyn:attributeWhenReady("host.name")`
+declared on entity X, and inherited by child entity Y. If entity Y uses this config value, 
+it will get the "host.name" attribute of entity X.
+
+Below is another (contrived!) example of this DSL evaluation. When evaluating `refExampleConfig`,
+it retrievies the value of `exampleConfig` which is the DSL expression, and evaluates this in the 
+context of the parent entity that declares it. Therefore `$brooklyn:config("ownConfig")` returns 
+the parent's `ownConfig` value, and the final result for `refExampleConfig` is set to "parentValue":
+
+{% highlight yaml %}
+services:
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+  brooklyn.config:
+    ownConfig: parentValue
+    exampleConfig: $brooklyn:config("ownConfig")
+  
+  brooklyn.children:
+  - type: org.apache.brooklyn.entity.stock.BasicEntity
+    brooklyn.config:
+      ownConfig: childValue
+      refExampleConfig: $brooklyn:config("exampleConfig")
+{% endhighlight %}
+
+_However, the web-console also shows other misleading (incorrect!) config values for the child 
+entity. It shows the inherited config value of `exampleConfig` as "childValue" (because the
+REST api did not evaluate the DSL in the correct context, when retrieving the value! 
+See https://issues.apache.org/jira/browse/BROOKLYN-455._
+
+
+#### 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 section [Configuration in a Catalog Item](#configuration-in-a-catalog-item)).
+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. 
+
+
+#### 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 %}
+
+
+#### Re-inherited Versus not Re-inherited
+
+For some configuration values, the most logical behaviour is for an entity to "consume" the config
+key's value, and thus not pass it down to children in the runtime type hierarchy. This is called
+"not re-inherited".
+
+Some common config keys that will not re-inherited include:
+
+* `install.command` (and the `pre.install.command` and `post.install.command`) 
+* `customize.command` (and the `pre.customize.command` and `post.customize.command`)
+* `launch.command` (and the ``pre.launch.command` and `post.launch.command`)
+* `checkRunning.command`
+* `stop.command`
+* The similar commands for `VanillaWindowsProcess` powershell.
+* The file and template install config keys (e.g. `files.preinstall`, `templates.preinstall`, etc)
+
+An example is shown below. Here, the "logstash-child" is a sub-type of `VanillaSoftwareProcess`,
+and is co-located on the same VM as Tomcat. We don't want the Tomcat's configuration, such as 
+`install.command`, to be inherited by the logstash child. If it was inherited, the logstash-child
+entity might re-execute the Tomcat's install command! Instead, the `install.command` config is
+"consumed" by the Tomcat instance and is not re-inherited:
+
+{% highlight yaml %}
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+  brooklyn.config:
+    children.startable.mode: background_late
+  brooklyn.children:
+  - type: logstash-child
+    brooklyn.config:
+      logstash.elasticsearch.host: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets")
+...
+{% endhighlight %}
+
+"Not re-inherited" differs from "never inherited". The example below illustrates the difference, 
+though this use is discouraged (it is mostly for backwards compatibility). The `post.install.command`
+is not consumed by the `BasicApplication`, so will be inherited by the `Tomcat8Server` which will
+consume it. The config value will therefore not be inherited by the `logstash-child`.
+
+{% highlight yaml %}
+services:
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+  brooklyn.config:
+    post.install.command: echo "My post.install command"
+  brooklyn.children:
+  - type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+    brooklyn.config:
+      children.startable.mode: background_late
+    brooklyn.children:
+    - type: logstash-child
+      brooklyn.config:
+        logstash.elasticsearch.host: $brooklyn:entity("es").attributeWhenReady("urls.http.withBrackets")
+...
+{% endhighlight %}
+
+
+#### Never Inherited
+
+For some configuration values, the most logical behaviour is for the value to never be inherited
+in the runtime management hiearchy.
+
+Some common config keys that will never inherited include:
+
+* `defaultDisplayName`: this is the name to use for the entity, if an explicit name is not supplied.
+  This is particularly useful when adding an entity in a catalog item (so if the user does not give
+  a name, it will get a sensible default). It would not be intuitive for all the children of that
+  entity to also get that default name.
+
+* `id`: the id of an entity (as supplied in the YAML, to allow references to that entity) is not 
+  inherited. It is the id of that specific entity, so must not be shared by all its children.
+
+
+#### Inheritance Modes: Deep Dive
+
+The javadoc in the code is useful for anyone who wants to go deep! See
+`org.apache.brooklyn.config.BasicConfigInheritance` and `org.apache.brooklyn.config.ConfigInheritances`
+in the repo https://github.com/apache/brooklyn-server.
+
+When defining a new config key, the exact semantics for inheritance can be defined. There are 
+separate options to control config inheritance from the super-type, and config inheritance from the
+parent in the runtime management hierarchy.
+
+The possible modes are:
+
+* `NEVER_INHERITED`: indicates that a key's value should never be inherited (even if defined on 
+  an entity that does not know the key). Most usages will prefer `NOT_REINHERITED`.
+
+* `NOT_REINHERITED`: indicates that a config key value (if used) should not be passed down to
+  children / sub-types. Unlike `NEVER_INHERITED`, these values can be passed down if they are not
+  used by the entity (i.e. if the entity does not expect it). However, when used by a child,
+  it will not be passed down any further. If the inheritor also defines a value the parent's 
+  value is ignored irrespective  (as in `OVERWRITE`; see `NOT_REINHERITED_ELSE_DEEP_MERGE` if merging 
+  is desired).
+
+* `NOT_REINHERITED_ELSE_DEEP_MERGE`: as `NOT_REINHERITED` but in cases where a value is inherited 
+  because a parent did not recognize it, if the inheritor also defines a value the two values should 
+  be merged.
+
+* `OVERWRITE`: indicates that if a key has a value at both an ancestor and a descendant, the 
+  descendant and his descendants will prefer the value at the descendant.
+
+* `DEEP_MERGE`: indicates that if a key has a value at both an ancestor and a descendant, the 
+  descendant and his descendants should attempt to merge the values. If the values are not mergable,
+  behaviour is undefined (and often the descendant's value will simply overwrite).
+
+
+#### Explicit Inheritance Modes
+
+_The YAML support for explicitly defining the inheritance mode is still work-in-progress. The options
+documented below will be enhanced in a future version of AMP, to better support the modes described
+above._
+
+In a YAML blueprint, within the `brooklyn.parameters` section for declaring new config keys, one can
+set the mode for `inheritance.type` and `inheritance.parent` (i.e. for inheritance from the super-type, and
+inheritance in the runtime management hierarchy). 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-inheritance-example
+    version: "1.1.0-SNAPSHOT"
+    itemType: entity
+    name: Entity Config Inheritance 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-inheritance-example
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+  name: app2
+  brooklyn.children:
+  - type: entity-config-inheritance-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-inheritance-example
+
+- type: org.apache.brooklyn.entity.stock.BasicApplication
+  name: app4
+  brooklyn.config:
+    example.map:
+      MESSAGE_IN_PARENT: InParent
+  brooklyn.children:
+  - type: entity-config-inheritance-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.
+
+
+#### Merging Policy and Enricher Configuration Values
+
+A current limitation is that sub-type inheritance is not supported for configuration of
+policies and enrichers. The current behaviour is that config is not inherited. The concept of
+inheritance from the runtime management hierarchy does not apply for policies and enrichers
+(they do not have "parents"; they are attached to an entity).

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml b/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml
new file mode 100644
index 0000000..64ed9a0
--- /dev/null
+++ b/guide/blueprints/example_yaml/appserver-clustered-w-db-concise.yaml
@@ -0,0 +1,15 @@
+name: appserver-clustered-w-db-concise
+services:
+- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+  brooklyn.config:
+    cluster.initial.size: 2
+    wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war
+    http.port: 8080+
+    java.sysprops: 
+      brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+           component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
+  id: db
+  name: DB HelloWorld Visitors
+  brooklyn.config:
+    datastore.creation.script.url: https://github.com/apache/brooklyn-library/blob/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml b/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml
new file mode 100644
index 0000000..a3fa749
--- /dev/null
+++ b/guide/blueprints/example_yaml/appserver-clustered-w-db.yaml
@@ -0,0 +1,19 @@
+name: appserver-clustered-w-db
+services:
+- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+  brooklyn.config:
+    cluster.initial.size: 2
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+        brooklyn.config:
+          wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war
+          http.port: 8080+
+          java.sysprops:
+            brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+                component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
+  id: db
+  name: DB HelloWorld Visitors
+  brooklyn.config:
+    datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-configured-in-config.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/appserver-configured-in-config.yaml b/guide/blueprints/example_yaml/appserver-configured-in-config.yaml
new file mode 100644
index 0000000..765a8c2
--- /dev/null
+++ b/guide/blueprints/example_yaml/appserver-configured-in-config.yaml
@@ -0,0 +1,6 @@
+name: appserver-configured-in-config
+services:
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+  brooklyn.config:
+    wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war
+    http.port: 8080

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-configured.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/appserver-configured.yaml b/guide/blueprints/example_yaml/appserver-configured.yaml
new file mode 100644
index 0000000..51bf3ca
--- /dev/null
+++ b/guide/blueprints/example_yaml/appserver-configured.yaml
@@ -0,0 +1,5 @@
+name: appserver-configured
+services:
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+  war: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war
+  httpPort: 8080

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml b/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml
new file mode 100644
index 0000000..9b648d8
--- /dev/null
+++ b/guide/blueprints/example_yaml/appserver-w-db-other-flavor.yaml
@@ -0,0 +1,17 @@
+name: appserver-w-db-other-flavor
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.TomcatServer
+  name: AppServer HelloWorld 
+  brooklyn.config:
+    wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war
+    http.port: 8080+
+    java.sysprops: 
+      brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+         component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: org.apache.brooklyn.entity.database.mariadb.MariaDbNode
+  id: db
+  name: DB HelloWorld Visitors
+  brooklyn.config:
+    datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql
+    provisioning.properties:
+      minRam: 8192

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-w-db.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/appserver-w-db.yaml b/guide/blueprints/example_yaml/appserver-w-db.yaml
new file mode 100644
index 0000000..d4bc706
--- /dev/null
+++ b/guide/blueprints/example_yaml/appserver-w-db.yaml
@@ -0,0 +1,15 @@
+name: appserver-w-db
+services:
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+  name: AppServer HelloWorld 
+  brooklyn.config:
+    wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war
+    http.port: 8080+
+    java.sysprops: 
+      brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+         component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
+  id: db
+  name: DB HelloWorld Visitors
+  brooklyn.config:
+    datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/appserver-w-policy.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/appserver-w-policy.yaml b/guide/blueprints/example_yaml/appserver-w-policy.yaml
new file mode 100644
index 0000000..4b10f59
--- /dev/null
+++ b/guide/blueprints/example_yaml/appserver-w-policy.yaml
@@ -0,0 +1,27 @@
+name: appserver-w-policy
+services:
+- type: org.apache.brooklyn.entity.webapp.ControlledDynamicWebAppCluster
+  brooklyn.config:
+    cluster.initial.size: 1
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+        brooklyn.config:
+          wars.root: http://search.maven.org/remotecontent?filepath=org/apache/brooklyn/example/brooklyn-example-hello-world-sql-webapp/0.8.0-incubating/brooklyn-example-hello-world-sql-webapp-0.8.0-incubating.war
+          http.port: 8080+
+          java.sysprops:
+            brooklyn.example.db.url: $brooklyn:formatString("jdbc:%s%s?user=%s\\&password=%s",
+                component("db").attributeWhenReady("datastore.url"), "visitors", "brooklyn", "br00k11n")
+  brooklyn.policies:
+  - type: org.apache.brooklyn.policy.autoscaling.AutoScalerPolicy
+    brooklyn.config:
+      metric: $brooklyn:sensor("brooklyn.entity.webapp.DynamicWebAppCluster", "webapp.reqs.perSec.windowed.perNode")
+      metricLowerBound: 10
+      metricUpperBound: 100
+      minPoolSize: 1
+      maxPoolSize: 5
+- type: org.apache.brooklyn.entity.database.mysql.MySqlNode
+  id: db
+  name: DB HelloWorld Visitors
+  brooklyn.config:
+    datastore.creation.script.url: https://github.com/apache/brooklyn-library/raw/master/examples/simple-web-cluster/src/main/resources/visitors-creation-script.sql

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/cluster-vm.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/cluster-vm.yaml b/guide/blueprints/example_yaml/cluster-vm.yaml
new file mode 100644
index 0000000..e21977a
--- /dev/null
+++ b/guide/blueprints/example_yaml/cluster-vm.yaml
@@ -0,0 +1,13 @@
+name: cluster-vm
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+  brooklyn.config:
+    cluster.initial.size: 5
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
+        name: VM
+        provisioning.properties:
+          minRam: 8g
+          minCores: 4
+          minDisk: 100g

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml b/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml
new file mode 100644
index 0000000..d923025
--- /dev/null
+++ b/guide/blueprints/example_yaml/fabric-with-multiple-locations.yaml
@@ -0,0 +1,15 @@
+name: fabric-of-app-server-clusters
+locations:
+- aws-ec2:us-east-1
+- aws-ec2:us-west-1
+services:
+- type: org.apache.brooklyn.entity.group.DynamicFabric
+  brooklyn.config:
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.entity.group.DynamicCluster
+        brooklyn.config:
+          cluster.initial.size: 3
+          dynamiccluster.memberspec:
+            $brooklyn:entitySpec:
+              type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml b/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml
new file mode 100644
index 0000000..7e4c0ca
--- /dev/null
+++ b/guide/blueprints/example_yaml/simple-appserver-with-location-byon.yaml
@@ -0,0 +1,10 @@
+name: simple-appserver-with-location-byon
+location:
+  byon:
+    user: brooklyn
+    privateKeyFile: ~/.ssh/brooklyn.pem
+    hosts:
+    - 192.168.0.18
+    - 192.168.0.19
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml b/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml
new file mode 100644
index 0000000..a39e27d
--- /dev/null
+++ b/guide/blueprints/example_yaml/simple-appserver-with-location-per-entity.yaml
@@ -0,0 +1,8 @@
+name: simple-appserver-with-location-per-entity
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+  location:
+    byon(hosts="192.168.0.18",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+  location:
+    byon(hosts="192.168.0.19",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver-with-location.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/simple-appserver-with-location.yaml b/guide/blueprints/example_yaml/simple-appserver-with-location.yaml
new file mode 100644
index 0000000..764eaac
--- /dev/null
+++ b/guide/blueprints/example_yaml/simple-appserver-with-location.yaml
@@ -0,0 +1,8 @@
+name: simple-appserver-with-location
+location:
+  jclouds:aws-ec2:
+    region: us-east-1
+    identity: AKA_YOUR_ACCESS_KEY_ID
+    credential: <access-key-hex-digits>
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-appserver.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/simple-appserver.yaml b/guide/blueprints/example_yaml/simple-appserver.yaml
new file mode 100644
index 0000000..8e9d76a
--- /dev/null
+++ b/guide/blueprints/example_yaml/simple-appserver.yaml
@@ -0,0 +1,4 @@
+name: simple-appserver
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/simple-vm.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/simple-vm.yaml b/guide/blueprints/example_yaml/simple-vm.yaml
new file mode 100644
index 0000000..8f6447c
--- /dev/null
+++ b/guide/blueprints/example_yaml/simple-vm.yaml
@@ -0,0 +1,8 @@
+name: simple-vm
+services:
+- type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
+  name: VM
+  provisioning.properties:
+    minRam: 8192mb
+    minCores: 4
+    minDisk: 100gb

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml b/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml
new file mode 100644
index 0000000..93b6795
--- /dev/null
+++ b/guide/blueprints/example_yaml/test-app-with-enrichers-slightly-simpler.yaml
@@ -0,0 +1,58 @@
+#
+# example showing how enrichers can be set 
+#
+name: test-app-with-enrichers
+description: Testing many enrichers
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+  id: cluster
+  location: localhost
+  brooklyn.config:
+    cluster.initial.size: 3
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: org.apache.brooklyn.core.test.entity.TestEntity
+        brooklyn.enrichers:
+        - type: org.apache.brooklyn.enricher.stock.Transformer
+          # transform "ip" (which we expect a feed, not shown here, to set) to a URL;
+          # you can curl an address string to the sensors/ip endpoint an entity to trigger these enrichers
+          brooklyn.config:
+            enricher.sourceSensor: $brooklyn:sensor("ip")
+            enricher.targetSensor: $brooklyn:sensor("url")
+            enricher.targetValue: $brooklyn:formatString("http://%s/", $brooklyn:attributeWhenReady("ip"))
+        - type: org.apache.brooklyn.enricher.stock.Propagator
+          # use propagator to duplicate one sensor as another, giving the supplied sensor mapping;
+          # the other use of Propagator is where you specify a producer (using $brooklyn:entity(...) as below)
+          # from which to take sensors; in that mode you can specify `propagate` as a list of sensors whose names are unchanged,
+          # instead of (or in addition to) this map
+          brooklyn.config:
+            sensorMapping:
+              $brooklyn:sensor("url"): $brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri")
+  brooklyn.enrichers:
+  - type: org.apache.brooklyn.enricher.stock.Aggregator
+    # aggregate `url` sensors from children into a list
+    brooklyn.config:
+      enricher.sourceSensor: $brooklyn:sensor("url")
+      enricher.targetSensor: $brooklyn:sensor("urls.list")
+      enricher.aggregating.fromMembers: true
+  - type: org.apache.brooklyn.enricher.stock.Joiner
+    # create a string from that list, for use e.g. in bash scripts
+    brooklyn.config:
+      enricher.sourceSensor: $brooklyn:sensor("urls.list")
+      enricher.targetSensor: $brooklyn:sensor("urls.list.comma_separated.max_2")
+      maximum: 2
+      # TODO infer uniqueTag, name etc
+      uniqueTag: urls.list.comma_separated.max_2
+  - type: org.apache.brooklyn.enricher.stock.Joiner
+    # pick one uri as the main one to use
+    brooklyn.config:
+      enricher.sourceSensor: $brooklyn:sensor("urls.list")
+      enricher.targetSensor: $brooklyn:sensor("org.apache.brooklyn.core.entity.Attributes", "main.uri")
+      quote: false
+      maximum: 1
+brooklyn.enrichers:
+- type: org.apache.brooklyn.enricher.stock.Propagator
+  # if nothing specified for `propagating` or `sensorMapping` then 
+  # Propagator will do all but the usual lifecycle defaults, handy at the root!
+  brooklyn.config:
+    producer: $brooklyn:entity("cluster")

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom b/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom
new file mode 100644
index 0000000..6416ab7
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-catalog.bom
@@ -0,0 +1,36 @@
+brooklyn.catalog:
+  id: netcat-example
+  version: "1.0"
+  itemType: entity
+  item:
+    type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+    name: Simple Netcat Server
+
+    launch.command: |
+      echo $MESSAGE | nc -l $NETCAT_PORT &
+      echo $! > $PID_FILE
+        
+    env:
+      MESSAGE: $brooklyn:config("message")
+      NETCAT_PORT: $brooklyn:attributeWhenReady("netcat.port")
+      
+    brooklyn.parameters:
+    - name: message
+      description: a message to send to the caller
+      default: hello
+    - name: netcat.port
+      type: port
+      description: the port netcat should run on
+      default: 4321+
+
+    brooklyn.enrichers:
+    - type: org.apache.brooklyn.enricher.stock.Transformer
+      brooklyn.config:
+        uniqueTag: main-uri-generator
+        enricher.sourceSensor: $brooklyn:sensor("host.address")
+        enricher.targetSensor: $brooklyn:sensor("main.uri")
+        enricher.targetValue:
+          $brooklyn:formatString:
+          - "http://%s:%s/"
+          - $brooklyn:attributeWhenReady("host.address")
+          - $brooklyn:attributeWhenReady("netcat.port")

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml
new file mode 100644
index 0000000..813445f
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-cluster.yaml
@@ -0,0 +1,12 @@
+name: Netcat Cluster Example
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.group.DynamicCluster
+  brooklyn.config:
+    dynamiccluster.memberspec:
+      $brooklyn:entitySpec:
+        type: netcat-example
+        message: hello from cluster member
+        netcat.port: 8000+
+    cluster.initial.size: 3
+    restartMode: parallel

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml
new file mode 100644
index 0000000..061d31b
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-env.yaml
@@ -0,0 +1,12 @@
+name: Netcat Example with Environment Vars
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+  name: Simple Netcat Server
+  launch.command: |
+    echo $MESSAGE | nc -l $NETCAT_PORT &
+    echo $! > $PID_FILE
+    
+  env:
+    MESSAGE: hello
+    NETCAT_PORT: 4321

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml
new file mode 100644
index 0000000..d768739
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-file.yaml
@@ -0,0 +1,6 @@
+name: Simple Netcat Example From File
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+  name: Simple Netcat Server
+  download.url: file:///tmp/netcat-server.tgz

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml
new file mode 100644
index 0000000..f4e894f
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-more-commands.yaml
@@ -0,0 +1,16 @@
+name: Netcat Example with Explicit Check and Stop Commands
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+  name: Simple Netcat Server
+  launch.command: |
+    echo hello | nc -l 4321 &
+    echo $! > $PID_FILE
+
+  # The following overrides demonstrate the use of a custom shell environment as well as
+  # check-running and stop commands. These are optional; default behavior will "do the
+  # right thing" with the pid file automatically.
+
+  env:                  { CHECK_MARKER: "checkRunning", STOP_MARKER: "stop" }
+  checkRunning.command: echo $CHECK_MARKER >> DATE && test -f "$PID_FILE" && ps -p `cat $PID_FILE` >/dev/null
+  stop.command:         echo $STOP_MARKER  >> DATE && test -f "$PID_FILE" && { kill -9 `cat $PID_FILE`; rm /tmp/vanilla.pid; }

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml
new file mode 100644
index 0000000..90f83b4
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-port-parameter.yaml
@@ -0,0 +1,21 @@
+name: Netcat Example with Parameter
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+  name: Simple Netcat Server
+  launch.command: |
+    echo $MESSAGE | nc -l $NETCAT_PORT &
+    echo $! > $PID_FILE
+    
+  env:
+    MESSAGE: $brooklyn:config("message")
+    NETCAT_PORT: $brooklyn:attributeWhenReady("netcat.port")
+  
+  brooklyn.parameters:
+  - name: message
+    description: a message to send to the caller
+    default: hello
+  - name: netcat.port
+    type: port
+    description: the port netcat should run on
+    default: 4321+

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml
new file mode 100644
index 0000000..3ec0212
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-port.yaml
@@ -0,0 +1,13 @@
+name: Netcat Example with Port Opened
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+  name: Simple Netcat Server
+  launch.command: |
+    echo hello | nc -l 4321 &
+    echo $! > $PID_FILE
+    
+  brooklyn.config:
+    # matching the regex `.*\.port` will cause the port to be opened
+    # if in a cloud where configurable security groups are available
+    netcat.port: 4321

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml
new file mode 100644
index 0000000..0f10c55
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-reference.yaml
@@ -0,0 +1,5 @@
+name: Netcat Type Reference Example
+location: localhost
+services:
+- type: netcat-example
+  message: hello from netcat using a registered type

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f38b9e7b/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml
----------------------------------------------------------------------
diff --git a/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml b/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml
new file mode 100644
index 0000000..47e54ab
--- /dev/null
+++ b/guide/blueprints/example_yaml/vanilla-bash-netcat-restarter.yaml
@@ -0,0 +1,20 @@
+name: Netcat Example with Restarter Policy
+location: localhost
+services:
+- type: org.apache.brooklyn.entity.software.base.VanillaSoftwareProcess
+  id: netcat-server
+  name: Simple Netcat Server
+  launch.command: |
+    echo hello | nc -l 4321 &
+    echo $! > $PID_FILE
+  brooklyn.enrichers:
+  - type: org.apache.brooklyn.policy.ha.ServiceFailureDetector
+    brooklyn.config:
+      # wait 15s after service fails before propagating failure
+      serviceFailedStabilizationDelay: 15s
+  brooklyn.policies:
+  - type: org.apache.brooklyn.policy.ha.ServiceRestarter
+    brooklyn.config:
+      # repeated failures in a time window can cause the restarter to abort,
+      # propagating the failure; a time window of 0 will mean it always restarts!
+      failOnRecurringFailuresInThisDuration: 0


Mime
View raw message