You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2015/01/09 16:35:01 UTC

[32/44] incubator-brooklyn git commit: breaks up YAML reference into smaller pages

breaks up YAML reference into smaller pages


Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/7bf8c7be
Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/7bf8c7be
Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/7bf8c7be

Branch: refs/heads/master
Commit: 7bf8c7be00b149ff73025ed90af5036a126707d2
Parents: 8a61e4c
Author: Robert Moss <ro...@gmail.com>
Authored: Thu Jan 8 14:40:25 2015 +0000
Committer: Robert Moss <ro...@gmail.com>
Committed: Fri Jan 9 15:19:28 2015 +0000

----------------------------------------------------------------------
 docs/guide/java/index.md                 |   6 +-
 docs/guide/start/blueprints.md           |   7 -
 docs/guide/start/config.md               |  50 ++++
 docs/guide/yaml/bigger-blueprint.md      |  43 ++++
 docs/guide/yaml/clusters-and-policies.md |  42 ++++
 docs/guide/yaml/clusters.md              |  34 +++
 docs/guide/yaml/configuring-vms.md       |  31 +++
 docs/guide/yaml/creating-yaml.md         | 344 +-------------------------
 docs/guide/yaml/custom-entities.md       | 107 ++++++++
 docs/guide/yaml/deploying-yaml.md        |  35 ---
 docs/guide/yaml/index.md                 |  12 +-
 docs/guide/yaml/multiple-services.md     |  64 +++++
 docs/guide/yaml/setting-locations.md     |  44 ++++
 13 files changed, 428 insertions(+), 391 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/java/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/java/index.md b/docs/guide/java/index.md
index 42fb3a5..f945e72 100644
--- a/docs/guide/java/index.md
+++ b/docs/guide/java/index.md
@@ -1,6 +1,6 @@
 ---
-title: Java
-title_in_menu: Java
+title: Java Blueprints
+title_in_menu: Java Blueprints
 layout: website-normal
 children:
 - walkthrough/
@@ -18,4 +18,4 @@ children:
 Java blueprints are much more powerful than YAML but is also rather more difficult.
 Advanced Java skills are required.
 
-{% include list-children.html %}
\ No newline at end of file
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/start/blueprints.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/blueprints.md b/docs/guide/start/blueprints.md
index 8effa07..2c85cbd 100644
--- a/docs/guide/start/blueprints.md
+++ b/docs/guide/start/blueprints.md
@@ -12,13 +12,6 @@ menu_parent: index.md
 
 Download the template [catalog.xml](catalog.xml) to your `~/.brooklyn/` folder, and relaunch Brooklyn.
 
-{% highlight bash %}
-$ cd ~/.brooklyn
-$ wget {{site.url_root}}{{site.path.guide}}/start/catalog.xml
-
-$ brooklyn launch
-{% endhighlight %}
-
 Now when we open the web console, two applications are displayed from the catalog.
 
 Select the 'Demo Web Cluster with DB' and click 'Next'.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/start/config.md
----------------------------------------------------------------------
diff --git a/docs/guide/start/config.md b/docs/guide/start/config.md
new file mode 100644
index 0000000..125553b
--- /dev/null
+++ b/docs/guide/start/config.md
@@ -0,0 +1,50 @@
+---
+title: Configuring Brooklyn
+title_in_menu: Configuring Brooklyn
+layout: guide-normal
+menu_parent: index.md
+---
+
+Brooklyn reads startup configuration from a file `~/.brooklyn/brooklyn.properties`, by default.
+You can create this from a template [brooklyn.properties]({{brooklyn_properties_url_path}}) file which you edit.
+
+## Configuring Security
+
+To configure Brooklyn to run on a public IP address, security should be enabled.
+The simplest way is to define a user and password in `~/.brooklyn/brooklyn.properties`
+(described above): 
+
+    brooklyn.webconsole.security.users=admin
+    brooklyn.webconsole.security.user.admin.password=s3cr3t
+
+Other modes, including LDAP, are described in this file.
+
+The other common setting is to run under https (on port 8443 by default):
+
+    brooklyn.webconsole.security.https.required=true
+
+## Configuring a Location
+
+Brooklyn deploys applications to locations. These locations
+can be clouds, machines with fixed IPs or localhost (for testing).
+Their configuration can be specified in `~/.brooklyn/brooklyn.properties` (described above),
+and then these locations can be easily selected within Brooklyn.
+Alternatively this information can be specified in the YAML when applications are deployed,
+without needing to set it in `brooklyn.properties`.
+
+Some sample settings for this are:
+
+    brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID
+    brooklyn.location.jclouds.aws-ec2.credential = <access-key-hex-digits>
+    brooklyn.location.named.aws-california = jclouds:aws-ec2:us-west-1
+    brooklyn.location.named.aws-california.displayName = AWS US West 1 (CA)
+
+    brooklyn.location.jclouds.softlayer.identity = username
+    brooklyn.location.jclouds.softlayer.credential = <private-key-hex-digits>
+    brooklyn.location.named.softlayer-dal05 = jclouds:softlayer:dal05
+    brooklyn.location.named.softlayer-dal05.displayName = Softlayer Dallas
+
+If you want to test Brooklyn on localhost, follow [these instructions]({{site.path.guide}}/use/guide/locations/) 
+to ensure that your Brooklyn can access your machine.
+
+Once updated, restart Brooklyn (or reload the properties within the web GUI).

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/bigger-blueprint.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/bigger-blueprint.md b/docs/guide/yaml/bigger-blueprint.md
new file mode 100644
index 0000000..1037063
--- /dev/null
+++ b/docs/guide/yaml/bigger-blueprint.md
@@ -0,0 +1,43 @@
+---
+title: A Bigger Blueprint
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+We've seen the configuration of machines and how to build up clusters.
+Now let's return to our app-server example and explore how more interesting
+services can be configured, composed, and combined.
+
+Also note there are some good overview materials [here]({{site.path.guide}}//use/guide/defining-applications/basic-concepts.html)
+covering clusters, sensors, effectors and more, 
+if you're the kind of person who likes to learn more about concepts before seeing them in action.
+
+
+### Service Configuration
+
+We'll begin by using more key-value pairs to configure the JBoss server to run a real app:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-configured.yaml %}
+{% endhighlight %}
+
+(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent examples.)
+
+When this is deployed, you can see management information in the Brooklyn Web Console,
+including a link to the deployed application (downloaded to the target machine from the `hello-world` URL),
+running on port 8080.
+
+**Top tip**:  If port 8080 might be in use, you can specify `8080+` to take the first available port >= 8080;
+the actual port will be reported as a sensor by Brooklyn.
+
+It's also worth indicating an alternate, more formal syntax.
+Not all configuration on entities is supported at the top level of the service specification
+(only those which are defined as "flags" in the underlying blueprint,
+e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`).
+All configuration has a formal qualified name, and this can be supplied even where flags or config keys are not
+explicitly defined, by placing it into a `brooklyn.config` section:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-configured-in-config.yaml %}
+{% endhighlight %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/clusters-and-policies.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/clusters-and-policies.md b/docs/guide/yaml/clusters-and-policies.md
new file mode 100644
index 0000000..e41115b
--- /dev/null
+++ b/docs/guide/yaml/clusters-and-policies.md
@@ -0,0 +1,42 @@
+---
+title: Clusters and Policies
+layout: guide-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 `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/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/clusters.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/clusters.md b/docs/guide/yaml/clusters.md
new file mode 100644
index 0000000..fc519a2
--- /dev/null
+++ b/docs/guide/yaml/clusters.md
@@ -0,0 +1,34 @@
+---
+title: Clusters, Specs, and Composition
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+What if you want multiple machines?
+
+One way is just to repeat the `- type: brooklyn.entity.basic.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 `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 `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/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/configuring-vms.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/configuring-vms.md b/docs/guide/yaml/configuring-vms.md
new file mode 100644
index 0000000..db08f0b
--- /dev/null
+++ b/docs/guide/yaml/configuring-vms.md
@@ -0,0 +1,31 @@
+---
+title: Configuring VMs
+layout: guide-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 }}/use/guide/defining-applications/basic-concepts.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 the javadoc on `JcloudsLocationConfig`.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/creating-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/creating-yaml.md b/docs/guide/yaml/creating-yaml.md
index 3cbd532..8b1b593 100644
--- a/docs/guide/yaml/creating-yaml.md
+++ b/docs/guide/yaml/creating-yaml.md
@@ -1,5 +1,5 @@
 ---
-title: Writing YAML Blueprints
+title: The Basic Structure
 layout: guide-normal
 toc: ../guide_toc.json
 categories: [use, guide, defining-applications]
@@ -41,348 +41,6 @@ and you can configure https and security, and much more, as described [here](dep
 [![Web Console](web-console-yaml-700.png "YAML via Web Console")](web-console-yaml.png)
 
 
-### Setting Locations
-
-Brooklyn supports a very wide range of target locations -- localhost is mainly a convenience for testing.
-With deep integration to [Apache jclouds](http://jclouds.org), most well-known clouds and cloud platforms are supported.
-The following example is for Amazon EC2:
-
-{% highlight yaml %}
-{% readj example_yaml/simple-appserver-with-location.yaml %}
-{% endhighlight %}
-
-(You'll need to replace the `identity` and `credential` with the 
-"Access Key ID" and "Secret Access Key" for your account,
-as configured in the [AWS Console](https://console.aws.amazon.com/iam/home?#security_credential).)
-
-Other popular public clouds include `softlayer`, `google-compute-engine`, and `rackspace-cloudservers-us`.
-Private cloud systems including `openstack-nova` and `cloudstack` are also supported,
-although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/` 
-(or `client/api/` in the case of CloudStack) instead of the `region`.
-
-You can also specify pre-existing servers to use -- "bring-your-own-nodes".
-These can be a global pool or specific to a service.
-Both styles are shown here (though normally only one will be selected,
-<!-- TODO see #1377, currently it is *parent* location which is preferred typically --> 
-depending on the blueprint):
-
-{% highlight yaml %}
-{% readj example_yaml/simple-appserver-with-location-byon.yaml %}
-{% endhighlight %}
-
-You'll also note in this example that we've used JSON-style notation in the second `location` block.
-YAML supports this, and sometimes that makes more readable plans.
-(Although in this case a simple `location: localhost` is equivalent and even more succinct, but this is a tutorial.)
-
-For more information see the Locations section of the [YAML reference](yaml-reference.html) 
-and in the [User's Guide]({{ site.path.guide }}/use/guide/locations/).
-Another good reference is the [template brooklyn.properties](/use/guide/quickstart/brooklyn.properties),
-which if you install in `~/.brooklyn/brooklyn.properties` and edit with your credentials,  
-allows you to refer to clouds simply as `location: jclouds:aws-ec2:eu-west-1` or
-set up "named locations" you can use as `location: named:my_cloudstack`.
-
-
-## Configuring VMs
-
-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 }}/use/guide/defining-applications/basic-concepts.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 the javadoc on `JcloudsLocationConfig`.
-
-
-### Clusters, Specs, and Composition
-
-What if you want multiple machines?
-
-One way is just to repeat the `- type: brooklyn.entity.basic.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 `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 `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.
-
-
-## A Bigger Blueprint
-
-We've seen the configuration of machines and how to build up clusters.
-Now let's return to our app-server example and explore how more interesting
-services can be configured, composed, and combined.
-
-Also note there are some good overview materials [here]({{site.path.guide}}//use/guide/defining-applications/basic-concepts.html)
-covering clusters, sensors, effectors and more, 
-if you're the kind of person who likes to learn more about concepts before seeing them in action.
-
-
-### Service Configuration
-
-We'll begin by using more key-value pairs to configure the JBoss server to run a real app:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-configured.yaml %}
-{% endhighlight %}
-
-(As before, you'll need to add the `location` info; `localhost` will work for these and subsequent examples.)
-
-When this is deployed, you can see management information in the Brooklyn Web Console,
-including a link to the deployed application (downloaded to the target machine from the `hello-world` URL),
-running on port 8080.
-
-**Top tip**:  If port 8080 might be in use, you can specify `8080+` to take the first available port >= 8080;
-the actual port will be reported as a sensor by Brooklyn.
-
-It's also worth indicating an alternate, more formal syntax.
-Not all configuration on entities is supported at the top level of the service specification
-(only those which are defined as "flags" in the underlying blueprint,
-e.g. the `@SetFromFlag("war")` in the `WebAppServiceConstants` parent of `JBoss7Server`).
-All configuration has a formal qualified name, and this can be supplied even where flags or config keys are not
-explicitly defined, by placing it into a `brooklyn.config` section:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-configured-in-config.yaml %}
-{% endhighlight %}
-
-
-
-### Multiple Services and Dependency Injection
-
-If you explored the `hello-world-sql` application we just deployed, 
-you'll have noticed it tries to access a database.
-And it fails, because we have not set one up.  Let's do that now:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-w-db.yaml %}
-{% endhighlight %}
-
-Here there are a few things going on:
-
-* We've added a second service, which will be the database;
-  you'll note the database has been configured to run a custom setup script
-* We've injected the URL of the second service into the appserver as a Java system property
-  (so our app knows where to find the database) 
-
-**Caution: Be careful if you write your YAML in an editor which attempts to put "smart-quotes" in.
-All quote characters must be plain ASCII, not fancy left-double-quotes and right-double-quotes!**
-
-There are as many ways to do dependency injection as there are developers,
-it sometimes seems; our aim in Brooklyn is not to say this has to be done one way,
-but to support the various mechanisms people might need to do, for whatever reasons.
-(We each have our opinions about what works well, of course;
-the one thing we do want to call out is that being able to dynamically update
-the injection is useful in a modern agile application -- so we are definitively **not**
-recommending this Java system property approach ... but it is an easy one to demo!)
-
-The way the dependency injection works is again by using the `$brooklyn:` DSL,
-this time referring to the `component("db")` (looked up by the `id` field on our DB component),
-and then to a sensor emitted by that component.
-All the database entities emit a `database.url` sensor when they are up and running;
-the `attributeWhenReady` DSL method will store a pointer to that sensor (a Java Future under the covers)
-in the Java system properties map which the JBoss entity reads at launch time, blocking if needed.
-
-This means that the deployment occurs in parallel, and if the database comes up first,
-there is no blocking; but if the JBoss entity completes its installation and 
-downloading the WAR, it will wait for the database before it launches.
-At that point the URL is injected, first passing it through `formatString`
-to include the credentials for the database (which are defined in the database creation script).
-
-
-
-### An Aside: Substitutability
-
-Don't like JBoss?  Is there something about Maria?
-One of the modular principles we follow in Brooklyn is substitutability:
-in many cases, the config keys, sensors, and effectors are defined
-in superclasses and are portable across multiple implementations.
-
-Here's an example deploying the same application but with different flavors of the components:
-
-{% highlight yaml %}
-{% readj example_yaml/appserver-w-db-other-flavor.yaml %}
-{% endhighlight %}
-
-We've also brought in the `provisioning.properties` from the VM example earlier
-so our database has 8GB RAM.
-Any of those properties, including `imageId` and `user`, can be defined on a per-entity basis.
-
-
-### Clusters and Policies
-
-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 `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.
-
-
-## New Custom Entities
-
-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`.  
-
-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. 
-We can specify a `download.url` which downloads artifacts (unpacking TAR, TGZ, and ZIP archives)
-before running `launch.command` relative to where that file is installed (or unpacked),
-with `./start.sh` being the default `launch.command`.
-
-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 %}
-
-The one requirement of the 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. 
-(There are other options; you can set `checkRunning.command` and `stop.command` instead,
-as documented on the Javadoc of the `VanillaSoftwareProcess` class,
-and those scripts will be used instead of checking and stopping the process whose PID is in `$PID_FILE`.)
-
-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 has stopped. 
-Besides detecting this failure, Brooklyn policies can be added to the YAML to take appropriate 
-action. A simple recovery here might just be to 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. 
-
-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:component("netcat-server").attributeWhenReady("host.name")
-      brooklyn.initializers:
-      - type: brooklyn.entity.software.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: brooklyn.entity.software.ssh.SshCommandSensor
-        brooklyn.config:
-          name: output.last
-          command: tail -1 server-input
-
-This is still a simple example, but worth going through carefully.
-It shows 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.
 
 <!--
 TODO building up children entities

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/custom-entities.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/custom-entities.md b/docs/guide/yaml/custom-entities.md
new file mode 100644
index 0000000..8e9638d
--- /dev/null
+++ b/docs/guide/yaml/custom-entities.md
@@ -0,0 +1,107 @@
+---
+title: Custom Entities
+layout: guide-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`.  
+
+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. 
+We can specify a `download.url` which downloads artifacts (unpacking TAR, TGZ, and ZIP archives)
+before running `launch.command` relative to where that file is installed (or unpacked),
+with `./start.sh` being the default `launch.command`.
+
+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 %}
+
+The one requirement of the 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. 
+(There are other options; you can set `checkRunning.command` and `stop.command` instead,
+as documented on the Javadoc of the `VanillaSoftwareProcess` class,
+and those scripts will be used instead of checking and stopping the process whose PID is in `$PID_FILE`.)
+
+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 has stopped. 
+Besides detecting this failure, Brooklyn policies can be added to the YAML to take appropriate 
+action. A simple recovery here might just be to 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. 
+
+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:component("netcat-server").attributeWhenReady("host.name")
+      brooklyn.initializers:
+      - type: brooklyn.entity.software.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: brooklyn.entity.software.ssh.SshCommandSensor
+        brooklyn.config:
+          name: output.last
+          command: tail -1 server-input
+
+This is still a simple example, but worth going through carefully.
+It shows 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/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/deploying-yaml.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/deploying-yaml.md b/docs/guide/yaml/deploying-yaml.md
deleted file mode 100644
index e4c3cf1..0000000
--- a/docs/guide/yaml/deploying-yaml.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Deploying YAML Blueprints
-layout: guide-normal
----
-
-Once you've [written a YAML blueprint](creating-yaml.md), there are several ways to deploy it.
-These insructions assume you have [installed]({{ site.path.guide }}/use/guide/quickstart/) Brooklyn.
-You can then:
-
-- Supply the YAML blueprint file on the CLI when launching the server:
-
-{% highlight bash %}
-$ brooklyn launch --app ./blueprint.yaml
-{% endhighlight %}
-
-
-Or, assuming you've launched a server already 
-(usually on [http://127.0.0.1:8081/](http://127.0.0.1:8081/) unless you've 
-configured security in [`brooklyn.properties`](/use/guide/quickstart/brooklyn.properties)),
-you can:
-
-- Curl it to the Brooklyn REST API:
-
-{% highlight bash %}
-$ curl -T ./blueprint.yaml -X POST http://localhost:8081/v1/applications
-{% endhighlight %}
-
-
-- In the web-console, select the "YAML" tab in the "Add Application" wizard:
-
-[![Web Console](web-console-yaml-700.png "YAML via Web Console")](web-console-yaml.png)
-
-
-- The web-console also has an interactive "REST API" page,
-  where you can paste the YAML for uploading into the `POST` to `/v1/applications`.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/index.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/index.md b/docs/guide/yaml/index.md
index d023ddb..f7147f5 100644
--- a/docs/guide/yaml/index.md
+++ b/docs/guide/yaml/index.md
@@ -1,12 +1,18 @@
 ---
-title: YAML
+title: YAML Blueprints
 layout: website-normal
 children:
 - creating-yaml.md
-- deploying-yaml.md
+- setting-locations.md
+- configuring-vms.md
+- clusters.md
+- bigger-blueprint.md
+- multiple-services.md
+- clusters-and-policies.md
+- custom-entities.md
 - catalog-maintenance.md
 - chef/
 - { path: yaml-reference.md, title: YAML Blueprint Reference }
 ---
 
-{% include list-children.html %}
\ No newline at end of file
+{% include list-children.html %}

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/multiple-services.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/multiple-services.md b/docs/guide/yaml/multiple-services.md
new file mode 100644
index 0000000..17e1f04
--- /dev/null
+++ b/docs/guide/yaml/multiple-services.md
@@ -0,0 +1,64 @@
+---
+title: Multiple Services and Dependency Injection
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+If you explored the `hello-world-sql` application we just deployed, 
+you'll have noticed it tries to access a database.
+And it fails, because we have not set one up.  Let's do that now:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-db.yaml %}
+{% endhighlight %}
+
+Here there are a few things going on:
+
+* We've added a second service, which will be the database;
+  you'll note the database has been configured to run a custom setup script
+* We've injected the URL of the second service into the appserver as a Java system property
+  (so our app knows where to find the database) 
+
+**Caution: Be careful if you write your YAML in an editor which attempts to put "smart-quotes" in.
+All quote characters must be plain ASCII, not fancy left-double-quotes and right-double-quotes!**
+
+There are as many ways to do dependency injection as there are developers,
+it sometimes seems; our aim in Brooklyn is not to say this has to be done one way,
+but to support the various mechanisms people might need to do, for whatever reasons.
+(We each have our opinions about what works well, of course;
+the one thing we do want to call out is that being able to dynamically update
+the injection is useful in a modern agile application -- so we are definitively **not**
+recommending this Java system property approach ... but it is an easy one to demo!)
+
+The way the dependency injection works is again by using the `$brooklyn:` DSL,
+this time referring to the `component("db")` (looked up by the `id` field on our DB component),
+and then to a sensor emitted by that component.
+All the database entities emit a `database.url` sensor when they are up and running;
+the `attributeWhenReady` DSL method will store a pointer to that sensor (a Java Future under the covers)
+in the Java system properties map which the JBoss entity reads at launch time, blocking if needed.
+
+This means that the deployment occurs in parallel, and if the database comes up first,
+there is no blocking; but if the JBoss entity completes its installation and 
+downloading the WAR, it will wait for the database before it launches.
+At that point the URL is injected, first passing it through `formatString`
+to include the credentials for the database (which are defined in the database creation script).
+
+
+
+### An Aside: Substitutability
+
+Don't like JBoss?  Is there something about Maria?
+One of the modular principles we follow in Brooklyn is substitutability:
+in many cases, the config keys, sensors, and effectors are defined
+in superclasses and are portable across multiple implementations.
+
+Here's an example deploying the same application but with different flavors of the components:
+
+{% highlight yaml %}
+{% readj example_yaml/appserver-w-db-other-flavor.yaml %}
+{% endhighlight %}
+
+We've also brought in the `provisioning.properties` from the VM example earlier
+so our database has 8GB RAM.
+Any of those properties, including `imageId` and `user`, can be defined on a per-entity basis.

http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/7bf8c7be/docs/guide/yaml/setting-locations.md
----------------------------------------------------------------------
diff --git a/docs/guide/yaml/setting-locations.md b/docs/guide/yaml/setting-locations.md
new file mode 100644
index 0000000..6feffe3
--- /dev/null
+++ b/docs/guide/yaml/setting-locations.md
@@ -0,0 +1,44 @@
+---
+title: Setting Locations
+layout: guide-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Brooklyn supports a very wide range of target locations -- localhost is mainly a convenience for testing.
+With deep integration to [Apache jclouds](http://jclouds.org), most well-known clouds and cloud platforms are supported.
+The following example is for Amazon EC2:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver-with-location.yaml %}
+{% endhighlight %}
+
+(You'll need to replace the `identity` and `credential` with the 
+"Access Key ID" and "Secret Access Key" for your account,
+as configured in the [AWS Console](https://console.aws.amazon.com/iam/home?#security_credential).)
+
+Other popular public clouds include `softlayer`, `google-compute-engine`, and `rackspace-cloudservers-us`.
+Private cloud systems including `openstack-nova` and `cloudstack` are also supported,
+although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/` 
+(or `client/api/` in the case of CloudStack) instead of the `region`.
+
+You can also specify pre-existing servers to use -- "bring-your-own-nodes".
+These can be a global pool or specific to a service.
+Both styles are shown here (though normally only one will be selected,
+<!-- TODO see #1377, currently it is *parent* location which is preferred typically --> 
+depending on the blueprint):
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver-with-location-byon.yaml %}
+{% endhighlight %}
+
+You'll also note in this example that we've used JSON-style notation in the second `location` block.
+YAML supports this, and sometimes that makes more readable plans.
+(Although in this case a simple `location: localhost` is equivalent and even more succinct, but this is a tutorial.)
+
+For more information see the Locations section of the [YAML reference](yaml-reference.html) 
+and in the [User's Guide]({{ site.path.guide }}/use/guide/locations/).
+Another good reference is the [template brooklyn.properties](/use/guide/quickstart/brooklyn.properties),
+which if you install in `~/.brooklyn/brooklyn.properties` and edit with your credentials,  
+allows you to refer to clouds simply as `location: jclouds:aws-ec2:eu-west-1` or
+set up "named locations" you can use as `location: named:my_cloudstack`.