Github user mikezaccardo commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/98#discussion_r73243661
--- Diff: guide/yaml/setting-locations.md ---
@@ -24,22 +29,98 @@ Private cloud systems including `openstack-nova` and
`cloudstack` are also suppo
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`.
+
+### "Bring Your Own Nodes" Example
+
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):
+The example below shows a pool of machines that will be used by the
entities within the
+application.
{% highlight yaml %}
{% readj example_yaml/simple-appserver-with-location-byon.yaml %}
{% endhighlight %}
-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 [Operations: Locations]({{ site.path.guide
}}/ops/locations) section of the User Guide.
-This includes support for defining locations externally in a
[brooklyn.properties]({{ brooklyn_properties_url_path }}) file,
-after which you can deploy to clouds or bring-your-own-nodes
-simply as `location: jclouds:aws-ec2:eu-west-1` or `location:
named:my_cloudstack`.
+### Single Line and Multi Line Locations
+
+A simple location can be specified on a single line. Alternatively, it can
be split to have one
+configuration option per line (recommended for all but the simplest
locations).
+
+For example, the two examples below are equivalent:
+
+{% highlight yaml %}
+location: byon(name="my
loc",hosts="1.2.3.4",user="bob",privateKeyFile="~/.ssh/bob_id_rsa")
+{% endhighlight %}
+
+{% highlight yaml %}
+location:
+ byon:
+ name: "my loc"
+ hosts:
+ - "1.2.3.4"
+ user: "bob"
+ privateKeyFile: "~/.ssh/bob_id_rsa"
+{% endhighlight %}
+
+
+### Specific Locations for Specific Entities
+
+One can define specific locations on specific entities within the
blueprint (instead of, or as
+well as, defining the location at the top-level of the blueprint).
+
+The example below will deploy Tomcat and JBoss App Server to different
Bring Your Own Nodes
+locations:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver-with-location-per-entity.yaml %}
+{% endhighlight %}
+
+The rules for precedence when defining a location for an entity are:
+
+* The location defined on that specific entity.
+* If no location, then the first ancestor that defines an explicit
location.
+* If still no location, then the location defined at the top-level of the
blueprint.
+
+This means, for example, that if you define an explicit location on a
cluster then it will be used
+for all members of that cluster.
+
+
+### Multiple Locations
+
+Some entities are written to expect a set of locations. For example, a
`DynamicFabric` will
+create a member entity in each location that it is given. To supply
multiple locations, simply
+use `locations` with a yaml list.
+
+In the example below, it will create a cluster of app-servers in each
location:
--- End diff --
Since your example is a `DynamicFabric` (X) of `DynamicCluster`s (Y) of web
servers (Z), you should clarify that one location is used for each entity Y,
and that all entities Z inside of Y are in the same location. This was not
readily apparent to me when I first used DF + DC with multiple locations.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
