brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [3/5] brooklyn-docs git commit: improve location yaml-syntax docs
Date Wed, 03 Aug 2016 21:27:01 GMT
improve location yaml-syntax docs


Branch: refs/heads/master
Commit: de1e235b4e4689a814112574e7b733b445684b65
Parents: 2be644e
Author: Aled Sage <>
Authored: Tue Aug 2 12:44:10 2016 +0100
Committer: Aled Sage <>
Committed: Wed Aug 3 22:22:55 2016 +0100

 guide/ops/locations/                    |  22 ++--
 .../fabric-with-multiple-locations.yaml         |  14 +++
 .../simple-appserver-with-location-byon.yaml    |   4 +-
 ...mple-appserver-with-location-per-entity.yaml |   8 ++
 .../simple-appserver-with-location.yaml         |   2 +-
 guide/yaml/                 | 109 ++++++++++++++++---
 6 files changed, 126 insertions(+), 33 deletions(-)
diff --git a/guide/ops/locations/ b/guide/ops/locations/
index fbcf35f..51f906a 100644
--- a/guide/ops/locations/
+++ b/guide/ops/locations/
@@ -6,21 +6,13 @@ children:
 check_directory_for_children: true
-Locations are the environments to which Brooklyn deploys applications, including:
+Locations are the environments to which Brooklyn deploys applications. Most commonly these

+are cloud services such as AWS, GCE, and IBM Softlayer. Brooklyn also supports deploying

+to a pre-provisioned network or to localhost (primarily useful for testing blueprints).
-Brooklyn supports a wide range of locations:
-* <a href="#clouds">Clouds</a>, where it will provision machines
-* <a href="#localhost">Localhost</a> (e.g. your laptop), 
-  where it will deploy via `ssh` to `localhost` for rapid testing
-* <a href="#byon">BYON</a>, where you "bring your own nodes",
-  specifying already-existing hosts to use
-* And many others, including object stores and online services
-Configuration can be set in `~/.brooklyn/`, through the
-location wizard tool available within the web console
-or directly in YAML when specifying a location.
-On some entities, config keys determining matching selection and provisioning behavior
-can also be set in ``.
+Also see the [Locations yaml guide]({{ }}/yaml/setting-locations.html),
+use within an entity of []({{ }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging),
+how to add location definitions to the [Catalog]({{ }}/ops/catalog/), 
+and how to use [Externalized Configuration](({{ }}/ops/externalized-configuration.html).
 {% child_content %}
diff --git a/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
new file mode 100644
index 0000000..3a7d3ab
--- /dev/null
+++ b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
@@ -0,0 +1,14 @@
+name: fabric-of-app-server-clusters
+- aws-ec2:us-east-1
+- aws-ec2:us-west-1
+- type:
+  brooklyn.config:
+    memberSpec:
+      $brooklyn:entitySpec:
+        type:
+        brooklyn.config:
+          memberSpec:
+            $brooklyn:entitySpec:
+              type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
index 8e9c951..7e4c0ca 100644
--- a/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
+++ b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
@@ -7,6 +7,4 @@ location:
-- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
-  location:
-    byon:(hosts="")
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
new file mode 100644
index 0000000..a39e27d
--- /dev/null
+++ b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
@@ -0,0 +1,8 @@
+name: simple-appserver-with-location-per-entity
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+  location:
+    byon(hosts="",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+  location:
+    byon(hosts="",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location.yaml b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
index 79344c8..764eaac 100644
--- a/guide/yaml/example_yaml/simple-appserver-with-location.yaml
+++ b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
@@ -5,4 +5,4 @@ location:
     identity: AKA_YOUR_ACCESS_KEY_ID
     credential: <access-key-hex-digits>
-- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
diff --git a/guide/yaml/ b/guide/yaml/
index ab92369..23ce6a4 100644
--- a/guide/yaml/
+++ b/guide/yaml/
@@ -7,8 +7,13 @@ categories: [use, guide, defining-applications]
 {% include %}
-Brooklyn supports a very wide range of target locations -- localhost is mainly a convenience
for testing.
-With deep integration to [Apache jclouds](, most well-known clouds and
cloud platforms are supported.
+Brooklyn supports a very wide range of target locations. 
+With deep integration to [Apache jclouds](, most well-known clouds

+and cloud platforms are supported. See the [Locations guide]({{ }}/ops/locations/)

+for details and more examples.
+### Cloud Example
 The following example is for Amazon EC2:
 {% highlight yaml %}
@@ -24,22 +29,98 @@ Private cloud systems including `openstack-nova` and `cloudstack` are
also suppo
 although for these you'll supply an `endpoint:` 
 (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 
 {% 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]({{ }}/ops/locations)
section of the User Guide.
-This includes support for defining locations externally in a []({{ 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
+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="",user="bob",privateKeyFile="~/.ssh/bob_id_rsa")
+{% endhighlight %}
+{% highlight yaml %}
+  byon:
+    name: "my loc"
+    hosts:
+    - ""
+    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
+{% 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:
+{% highlight yaml %}
+{% readj example_yaml/fabric-with-multiple-locations.yaml %}
+{% endhighlight %}
+For brevity, this example excludes the credentials for aws-ec2. These could either be specificed
+in-line or defined as named locations in the catalog (see below).
+### Adding Locations to the Catalog
+The examples above have given all the location details within the application blueprint.
+It is also possible (and indeed preferred) to add the location definitions to the catalog
+so that they can be referenced by name in any blueprint.
+For more information see the [Operations: Catalog]({{ }}/ops/catalog/) section
+the User Guide.
+### Externalized Configuration
+For simplicity, the examples above have included the cloud credentials. For a production
+it is strongly recommended to use [Externalized Configuration]({{ }}/ops/externalized-configuration.html)
+to retrieve the credentials from a secure credentials store, such as [Vault](
+### Use of
+An entity that represents a "software process" can use the configuration option 
+`` to augment the location's configuration. For more information,
+[Entity Configuration]({{ }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging)

View raw message