You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by dr...@apache.org on 2017/06/16 15:21:51 UTC
[11/28] brooklyn-docs git commit: Refactor Blueprinting
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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-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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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/1330dcd3/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